About gtk:

This is the API documentation of a Lisp binding to GTK. GTK is a library for creating graphical user interfaces. It works on many UNIX-like platforms, Windows, and OS X. GTK is released under the GNU Library General Public License (GNU LGPL), which allows for flexible licensing of client applications. GTK has a C-based object-oriented architecture that allows for maximum flexibility. Bindings for many other languages have been written, including C++, Objective-C, Guile/Scheme, Perl, Python, TOM, Ada95, Free Pascal, and Eiffel.

About gdk:

GDK is an intermediate layer which isolates GTK from the details of the windowing system. This is the API documentation of a Lisp binding to GDK.

About gsk:

GTK Scene Graph Kit (GSK) is the rendering and scene graph API for GTK introduced with version 3.90. GSK lies between the graphical control elements (widgets) and the rendering. Like GDK, GSK is part of GTK and licensed under the GNU Lesser General Public License (LGPL). This is the API documentation of a Lisp binding to GSK.

About gdk-pixbuf:

GDK-Pixbuf is a library for image loading and manipulation. The GDK-Pixbuf documentation contains both the programmer's guide and the API reference. This is the API documentation of a Lisp binding to the GDK-Pixbuf library.

About glib:

GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. It works on many UNIX-like platforms, as well as Windows and OS X. GLib is released under the GNU Library General Public License (GNU LGPL).

This is the API documentation of a Lisp binding to the library GLib. Only a small part of GLib is implemented in Lisp which is necessary to implement GTK in Lisp.

About gobject:

GObject provides the object system used for Pango and GTK. This is the API documentation of a Lisp binding to GObject.

About gio:

This is the API documentation of a Lisp binding to GIO. GIO is striving to provide a modern, easy-to-use VFS API that sits at the right level in the library stack, as well as other generally useful APIs for desktop applications (such as networking and D-Bus support). The goal is to overcome the shortcomings of GnomeVFS and provide an API that is so good that developers prefer it over raw POSIX calls. Among other things that means using GObject. It also means not cloning the POSIX API, but providing higher-level, document-centric interfaces.

About pango:

Pango is a text layout and shaping library. Pango facilitates the layout and shaping of multi-language text. Full-function rendering of text and cross-platform support is had when Pango is used with platform APIs or 3rd party libraries, such as Uniscribe and FreeType, as text rendering backends. Pango-processed text will appear similar under different operating systems. This is the API documentation of a Lisp binding to Pango.

About cairo:

Cairo is a software library used to provide a vector graphics-based, device-independent API for software developers. It is designed to provide primitives for 2-dimensional drawing across a number of different backends. Cairo is designed to use hardware acceleration when available. This is the API documentation of a Lisp binding to Cairo.

About graphene:

The Graphene library is a thin layer of mathematical types for 3D libraries. The library is implemented for use with the cl-cffi-gtk4 library. This is the API documentation for the Lisp binding to the Graphene library.

Contents


Package gtk

This is the API documentation of a Lisp binding to GTK. GTK is a library for creating graphical user interfaces. It works on many UNIX-like platforms, Windows, and OS X. GTK is released under the GNU Library General Public License (GNU LGPL), which allows for flexible licensing of client applications. GTK has a C-based object-oriented architecture that allows for maximum flexibility. Bindings for many other languages have been written, including C++, Objective-C, Guile/Scheme, Perl, Python, TOM, Ada95, Free Pascal, and Eiffel.

GListModel support

GtkBitset

GBoxed gtk:bitset
Declaration:
(glib:define-gboxed-opaque bitset "GtkBitset"
  :export t
  :type-initializer "gtk_bitset_get_type"
  :alloc (%bitset-new-empty))  
Returned by:
Details:
The gtk:bitset structure is a data structure for representing a set of unsigned integers. Another name for this data structure is "bitmap". The current implementation is based on roaring bitmaps.

A bitset allows adding a set of integers and provides support for set operations like unions, intersections and checks for equality or if a value is contained in the bitset. The gtk:bitset implementation also contains various functions to query metadata about the bitset, such as the minimum or maximum values or its size.

The fastest way to iterate values in a bitset is a gtk:bitset-iter iterator.

The main use case for the gtk:bitset structure is implementing complex selections for the gtk:selection-model class.
See also:
2025-3-13
Function gtk:bitset-new-empty ()
Returns:
The new empty gtk:bitset instance.
Details:
Creates a new empty bitset.
See also:
2025-3-13
Function gtk:bitset-new-range (start n)
Arguments:
start -- an unsigned integer for the first value to add
n -- an unsigned integer for the number of consecutive values to add
Returns:
The new gtk:bitset instance.
Details:
Creates a bitset with the given range set.
See also:
2025-3-13
Function gtk:bitset-copy (bitset)
Arguments:
bitset -- a gtk:bitset instance
Returns:
The new gtk:bitset instance that contains the same values as bitset.
Details:
Creates a copy of the bitset.
See also:
2025-3-13
Function gtk:bitset-contains (bitset value)
Arguments:
bitset -- a gtk:bitset instance
value -- an unsigned integer for the value to check
Returns:
True if bitset contains value.
Details:
Checks if the given value has been added to the bitset.
Examples:
(defvar bitset (gtk:bitset-new-range 100 50)) => BITSET
(gtk:bitset-contains bitset 99) => NIL
(gtk:bitset-contains bitset 100) => T
(gtk:bitset-contains bitset 149) => T
(gtk:bitset-contains bitset 150) => NIL    
See also:
2025-3-13
Function gtk:bitset-is-empty (bitset)
Arguments:
bitset -- a gtk:bitset instance
Returns:
True if bitset is empty.
Details:
Checks if no value is contained in the bitset.
See also:
2025-3-13
Function gtk:bitset-equals (bitset other)
Arguments:
bitset -- a gtk:bitset instance
other -- another gtk:bitset instance
Returns:
True if bitset and other contain the same values.
Details:
Returns true if bitset and other contain the same values.
See also:
2025-3-13
Function gtk:bitset-minimum (bitset)
Arguments:
bitset -- a gtk:bitset instance
Returns:
The unsigned integer with the smallest value in bitset.
Details:
Returns the smallest value in the bitset. If the bitset is empty, the maximum value for an unsigned 32-bit integer variable is returned, that is the #xffffffff value.
Examples:
(defvar bitset (gtk:bitset-new-range 100 50)) => BITSET
(gtk:bitset-minimum bitset) => 100
(gtk:bitset-maximum bitset) => 149
(gtk:bitset-minimum (gtk:bitset-new-empty)) => 4294967295
(gtk:bitset-maximum (gtk:bitset-new-empty)) => 0    
See also:
2025-3-13
Function gtk:bitset-maximum (bitset)
Arguments:
bitset -- a gtk:bitset instance
Returns:
The unsigned integer with the largest value in bitset.
Details:
Returns the largest value in the bitset. If the bitset is empty, 0 is returned. See the gtk:bitset-minimum documentation for examples.
See also:
2025-3-13
Function gtk:bitset-size (bitset)
Arguments:
bitset -- a gtk:bitset instance
Returns:
The unsigned integer with the number of values in bitset.
Details:
Gets the number of values that were added to the bitset. For example, if the bitset is empty, 0 is returned.
Examples:
(defvar bitset (gtk:bitset-new-range 100 50)) => BITSET
(gtk:bitset-size bitset) => 50    
See also:
2025-3-13
Function gtk:bitset-size-in-range (bitset first last)
Arguments:
bitset -- a gtk:bitset instance
first -- an unsigned integer for the first element to include
last -- an unsigned integer for the last element to include
Returns:
The unsigned integer with the number of values in the set from first to last.
Details:
Gets the number of values that are part of the bitset from first to last (inclusive).
See also:
2025-3-13
Function gtk:bitset-nth (bitset nth)
Arguments:
bitset -- a gtk:bitset instance
nth -- an unsigned integer for the index of the item to get
Returns:
The unsigned integer for the value of the nth item in bitset.
Details:
Returns the value of the nth item in the bitset. If nth is greater than or equal the size of the bitset, 0 is returned.
Examples:
(defvar bitset (gtk:bitset-new-range 100 50)) => BITSET
(gtk:bitset-size bitset) => 50
(gtk:bitset-nth bitset 0) => 100
(gtk:bitset-nth bitset 49) => 149    
See also:
2025-3-13
Function gtk:bitset-remove-all (bitset)
Arguments:
bitset -- a gtk:bitset instance
Details:
Removes all values from the bitset so that it is empty again.
See also:
2025-3-13
Function gtk:bitset-add (bitset value)
Arguments:
bitset -- a gtk:bitset instance
value -- an unsigned integer for the value to add
Returns:
True if value was not part of bitset and bitset was changed.
Details:
Adds value to the bitset if it was not part of it before.
See also:
2025-3-13
Function gtk:bitset-remove (bitset value)
Arguments:
bitset -- a gtk:bitset instance
value -- an unsigned integer for the value to remove
Returns:
True if value was part of bitset and bitset was changed.
Details:
Removes value from the bitset if it was part of it before.
See also:
2025-3-13
Function gtk:bitset-add-range (bitset start n)
Arguments:
bitset -- a gtk:bitset instance
start -- an unsigned integer for the first value to add
n -- an unsigned integer for the number of consecutive values to add
Details:
Adds all values from start (inclusive) to start + n (exclusive) in the bitset.
See also:
2025-3-13
Function gtk:bitset-remove-range (bitset start n)
Arguments:
bitset -- a gtk:bitset instance
start -- an unsigned integer for the first value to remove
n -- an unsigned integer for the number of consecutive values to remove
Details:
Removes all values from start (inclusive) to start + n (exclusive) in the bitset.
See also:
2025-3-13
Function gtk:bitset-add-range-closed (bitset first last)
Arguments:
bitset -- a gtk:bitset instance
first -- an unsigned integer for the first value to add
last -- an unsigned integer for the last value to add
Details:
Adds the closed range [first,last], so the first value, the last value and all values in between. The first value must be smaller than the last value.
See also:
2025-3-13
Function gtk:bitset-remove-range-closed (bitset first last)
Arguments:
bitset -- a gtk:bitset instance
first -- an unsigned integer for the first value to remove
last -- an unsigned integer for the last value to remove
Details:
Removes the closed range [first,last], so the first value, the last value and all values in between. The first value must be smaller than the last value.
See also:
2025-3-13
Function gtk:bitset-add-rectangle (bitset start width height stride)
Arguments:
bitset -- a gtk:bitset instance
start -- an unsigned integer for the first value to add
width -- an unsigned integer for the width of the rectangle
height -- an unsigned integer for the height of the rectangle
stride -- an unsigned integer for the row stride of the grid
Details:
Interprets the values as a 2-dimensional boolean grid with the given stride and inside that grid, adds a rectangle with the given width and height.
Notes:
This funtion is equivalent to:
(dotimes (i height)
  (gtk:bitset-add-range bitset (+ (* i stride) start) width))    
See also:
2025-3-13
Function gtk:bitset-remove-rectangle (bitset start width height stride)
Arguments:
bitset -- a gtk:bitset instance
start -- an unsigned integer for the first value to remove
width -- an unsigned integer for the width of the rectangle
height -- an unsigned integer for the height of the rectangle
stride -- an unsigned integer for the row stride of the grid
Details:
Interprets the values as a 2-dimensional boolean grid with the given stride and inside that grid, removes a rectangle with the given width and height.
Notes:
This funtion is equivalent to:
(dotimes (i height)
  (gtk:bitset-remove-range bitset (+ (* i stride) start) width))    
See also:
2025-3-13
Function gtk:bitset-union (bitset other)
Arguments:
bitset -- a gtk:bitset instance
other -- a gtk:bitset instance to union with
Details:
Sets bitset to be the union of bitset and other, that is add all values from other into bitset that were not part of it. It is allowed for bitset and other to be the same bitset. Nothing will happen in that case.
See also:
2025-3-13
Function gtk:bitset-intersect (bitset other)
Arguments:
bitset -- a gtk:bitset instance
other -- a gtk:bitset instance to intersect with
Details:
Sets bitset to be the intersection of bitset and other, that is remove all values from bitset that are not part of other. It is allowed for bitset and other to be the same bitset. Nothing will happen in that case.
See also:
2025-3-13
Function gtk:bitset-subtract (bitset other)
Arguments:
bitset -- a gtk:bitset instance
other -- a gtk:bitset instance to subtract
Details:
Sets bitset to be the subtraction of bitset from other, that is remove all values from bitset that are part of other. It is allowed for bitset and other to be the same bitset. The bitset will be emptied in that case.
See also:
2025-3-13
Function gtk:bitset-difference (bitset other)
Arguments:
bitset -- a gtk:bitset instance
other -- a gtk:bitset instance to compute the difference from
Details:
Sets bitset to be the symmetric difference of bitset and other, that is set bitset to contain all values that were either contained in bitset or in other, but not in both. This operation is also called an XOR. It is allowed for bitset and other to be the same bitset. The bitset will be emptied in that case.
See also:
2025-3-13
Function gtk:bitset-shift-left (bitset amount)
Arguments:
bitset -- a gtk:bitset instance
amount -- an unsigned integer for the amount to shift all values to left
Details:
Shifts all values in bitset to the left by amount. Values smaller than amount are discarded.
See also:
2025-3-13
Function gtk:bitset-shift-right (bitset amount)
Arguments:
bitset -- a gtk:bitset instance
amount -- an unsigned integer for the amount to shift all values to right
Details:
Shifts all values in bitset to the right by amount. Values that end up too large to be held in an unsigned 32-bit integer are discarded.
See also:
2025-3-13
Function gtk:bitset-splice (bitset position removed added)
Arguments:
bitset -- a gtk:bitset instance
position -- an unsigned integer for the position at which to slice
removed -- an unsigned integer for the number of values to remove
added -- an unsigned integer for the number of values to add
Details:
This is a support function for g:list-model handling, by mirroring the "items-changed" signal. First, it "cuts" the values from position to be removed from the bitset. That is, it removes all those values and shifts all larger values to the left by removed places. Then, it "pastes" new room into the bitset by shifting all values larger than position by added spaces to the right. This frees up space that can then be filled.
See also:
2025-3-13
CStruct gtk:bitset-iter
Declaration:
(cffi:defctype bitset-iter :pointer)  
Details:
An opaque, stack-allocated structure for iterating over the elements of a gtk:bitset instance. Before a gtk:bitset-iter instance can be used, it needs to be initialized with the gtk:bitset-iter-init-first, gtk:bitset-iter-init-last or gtk:bitset-iter-init-at function.
See also:
2025-3-13
Function gtk:bitset-iter-init-first (iter bitset)
Arguments:
iter -- an uninitialized gtk:bitset-iter instance
bitset -- a gtk:bitset instance
Returns:
The unsigned integer with the first value in bitset, or nil if bitset is empty.
Details:
Initializes an iterator for the bitset and points it to the first value in the bitset. If the bitset is empty, nil is returned.
See also:
2025-3-13
Function gtk:bitset-iter-init-last (iter bitset)
Arguments:
iter -- an uninitialized gtk:bitset-iter instance
bitset -- a gtk:bitset instance
Returns:
The unsigned integer with the last value in bitset, or nil if the bitset is empty.
Details:
Initializes an iterator for the bitset and points it to the last value in the bitset. If the bitset is empty, nil is returned.
See also:
2025-3-13
Function gtk:bitset-iter-init-at (iter bitset target)
Arguments:
iter -- an uninitialized gtk:bitset-iter instance
bitset -- a gtk:bitset instance
target -- an unsigned integer for the target value to start iterating at
Returns:
The unsigned integer with the found value in bitset, or nil.
Details:
Initializes an iterator for the bitset to point to target. If target is not found, finds the next value after it. If no value greater than or equal target exists in the bitset, this function returns nil.
See also:
2025-3-13
Function gtk:bitset-iter-next (iter)
Arguments:
iter -- a valid gtk:bitset-iter instance
Returns:
The unsigned integer with the next value in bitset, or nil if no next value existed.
Details:
Moves iter to the next value in the bitset. If it was already pointing to the last value in the bitset, nil is returned and iter is invalidated.
See also:
2025-3-13
Function gtk:bitset-iter-previous (iter)
Arguments:
iter -- a valid gtk:bitset-iter instance
Returns:
The unsigned integer with the previous value in bitset, or nil if iter was already pointing to the first value.
Details:
Moves iter to the previous value in the bitset. If it was already pointing to the first value in the bitset, nil is returned and iter is invalidated.
See also:
2025-3-13
Function gtk:bitset-iter-value (iter)
Arguments:
iter -- a valid gtk:bitset-iter instance
Returns:
The unsigned integer with the current value iter points to.
Details:
Gets the current value that iter points to. If iter is not valid and the gtk:bitset-iter-is-valid function returns false, this function returns 0.
See also:
2025-3-13
Function gtk:bitset-iter-is-valid (iter)
Arguments:
iter -- a gtk:bitset-iter instance
Returns:
True if iter points to a valid value.
Details:
Checks if iter points to a valid value.
See also:
2025-3-13

GtkExpression

GtkExpression gtk:expression
Superclasses:
common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:expression type provides a way to describe references to values. An important aspect of expressions is that the value can be obtained from a source that is several steps away. For example, an expression may describe "the value of property A of object1, which is itself the value of a property of object2". And object1 may not even exist yet at the time that the expression is created. This is contrast to GObject property bindings, which can only create direct connections between the properties of two objects that must both exist for the duration of the binding.

An expression needs to be "evaluated" to obtain the value that it currently refers to. An evaluation always happens in the context of a current object called this (it mirrors the behavior of object-oriented languages), which may or may not influence the result of the evaluation. Use the gtk:expression-evaluate function for evaluating an expression.

Various methods for defining expressions exist, from simple constants via the gtk:constant-expression-new function to looking up properties in a GObject (even recursively) via the gtk:property-expression-new function or providing custom functions to transform and combine expressions via the gtk:closure-expression-new function.

Here is an example of a complex expression:
(setf color (gtk:property-expression-new "GtkListItem" nil "item"))
(setf expression (gtk:property-expression-new "GtkColor" color "name"))  
when evaluated with this being a gtk:list-item object, it will obtain the item property from the gtk:list-item object, and then obtain the name property from the resulting object, which is assumed to be of type "GtkColor". A more concise way to describe this would be
this->item->name  
The most likely place where you will encounter expressions is in the context of list models and list widgets using them. For example, the gtk:drop-down widget is evaluating a gtk:expression instance to obtain strings from the items in its model that it can then use to match against the contents of its search entry. The gtk:string-filter object is using a gtk:expression instance for similar reasons.

By default, expressions are not paying attention to changes and evaluation is just a snapshot of the current state at a given time. To get informed about changes, an expression needs to be "watched" via a gtk:expression-watch instance, which will cause a callback to be called whenever the value of the expression may have changed. The gtk:expression-watch function starts watching an expression, and the gtk:expression-watch-unwatch function stops.

Watches can be created for automatically updating the property of an object, similar to GObject's GBinding mechanism, by using the gtk:expression-bind function.

GtkExpression in .ui files
The gtk:builder class has support for creating expressions. The syntax here can be used where a gtk:expression instance is needed like in a <property> tag for an expression property, or in a <binding> tag to bind a property to an expression.

To create an property expression, use the <lookup> element. It can have a type attribute to specify the object type, and a name attribute to specify the property to look up. The content of <lookup> can either be an element specfiying the expression to use the object, or a string that specifies the name of the object to use.

Examples:
<lookup name='search'>string_filter</lookup>  
To create a constant expression, use the <constant> element. If the type attribute is specified, the element content is interpreted as a value of that type. Otherwise, it is assumed to be an object. For instance:
<constant>string_filter</constant>
<constant type='gchararray'>Hello, world</constant>  
To create a closure expression, use the <closure> element. The type and function attributes specify what function to use for the closure, the content of the element contains the expressions for the parameters. For instance:
<closure type='gchararray' function='combine_args_somehow'>
  <constant type='gchararray'>File size:</constant>
  <lookup type='GFile' name='size'>myfile</lookup>
</closure>  
2025-3-14
Function gtk:expression-ref (expression)
Arguments:
expression -- a gtk:expression instance
Returns:
The gtk:expression instance with an additional reference.
Details:
Acquires a reference on the given expression.
See also:
2025-3-14
Function gtk:expression-unref (expression)
Arguments:
expression -- a gtk:expression instance
Details:
Releases a reference on the given gtk:expression instance. If the reference was the last, the resources associated to the expression are freed.
See also:
2025-3-14
Function gtk:expression-value-type (expression)
Arguments:
expression -- a gtk:expression instance
Returns:
The g:type-t type ID returned from the gtk:expression-evaluate function.
Details:
Gets the GType that this expression evaluates to. This type is constant and will not change over the lifetime of the expression.
See also:
2025-3-14
Function gtk:expression-is-static (expression)
Arguments:
expresson -- a gtk:expression instance
Returns:
True if expression is static.
Details:
Checks if the expression is static. A static expression will never change its result when the gtk:expression-evaluate function is called on it with the same arguments. That means a call to the gtk:expression-watch function is not necessary because it will never trigger a notify.
See also:
2025-3-14
Function gtk:expression-evaluate (expression object value)
Arguments:
expression -- a gtk:expression instance
object -- a g:object instance for the evaluation
value -- an initialized g:value instance
Returns:
True if the expression could be evaluated.
Details:
Evaluates the given expression and on success stores the result as a g:value instance in gvalue. The GType of the returned value will be the type given by the gtk:expression-value-type function.

It is possible that expressions cannot be evaluated - for example when the expression references objects that have been destroyed. In that case false will be returned.

See the gtk:expression-evaluate-value function for a variant that does not need an g:value instance, but returns the value.
See also:
2025-3-14
Function gtk:expression-evaluate-value (expression object)
Arguments:
expression -- a gtk:expression instance
object -- a g:object instance for the evaluation
Returns:
The evaluated value of the expression.
Details:
Evaluates the given expression and on success returns the result. This is a variant of the gtk:expression-evaluate function that avoids the usage of a g:value instance to get the value of the expression.
See also:
2025-3-14
Function gtk:expression-bind (expression target property source)
Arguments:
expression -- a gtk:expression instance
target -- a g:object instance for the target to bind to
property -- a string for the name of the property on target to bind to
source -- a g:object instance for the argument for the evaluation of expression
Returns:
The gtk:expression-watch instance.
Details:
Bind target's property named property to expression. The value that expression evaluates to is set on target. This is repeated whenever expression changes to ensure that the object's property stays synchronized with expression.

If expression's evaluation fails, target's property is not updated. You can ensure that this does not happen by using a fallback expression.

Note that this function takes ownership of expression. If you want to keep it around, you should use the gtk:expression-ref function beforehand.
See also:
2025-3-14
Callback gtk:expression-notify
Syntax:
lambda ()
Details:
Callback called by the gtk:expression-watch function when the expression value changes.
See also:
2025-3-14
Function gtk:expression-watch (expression object func)
Arguments:
expression -- a gtk:expression intstance
object -- a g:object instance for the argument to watch
func -- a gtk:expression-notify callback function to invoke when the expression changes
Returns:
The newly installed gtk:expression-watch instance. Note that the only reference held to the watch will be released when the watch is unwatched which can happen automatically, and not just via the gtk:expression-watch-unwatch function.
Details:
Installs a watch for the given expression that calls the notify function whenever the evaluation of expression may have changed. GTK cannot guarantee that the evaluation did indeed change when the notify gets invoked, but it guarantees the opposite: When it did in fact change, the notify will be invoked.
See also:
2025-3-14
GBoxed gtk:expression-watch
Declaration:
(glib:define-gboxed-opaque expression-watch "GtkExpressionWatch"
  :export t
  :type-initializer "gtk_expression_watch_get_type"
  :alloc (error "GtkExpressionWatch cannot be created from the Lisp side."))  
Details:
An opaque structure representing a watched gtk:expression instance.
See also:
2025-3-14
Function gtk:expression-watch-evaluate (watch value)
Arguments:
watch -- a gtk:expression-watch instance
value -- an initialized g:value instance
Details:
Evaluates the watched expression and on success returns the result in value. This is equivalent to calling the gtk:expression-evaluate function with the expression and the object originally used to create watch.

See the gtk:expression-watch-evaluate-value function which returns the value and does not need a g:value instance.
See also:
2025-3-14
Function gtk:expression-watch-evaluate-value (watch)
Arguments:
watch -- a gtk:expression-watch instance
Returns:
The value with the result.
Details:
Evaluates the watched expression and on success returns the result. This is equivalent to calling the gtk:expression-evaluate function with the expression and the object originally used to create watch.

This function is a variant of the gtk:expression-watch-evaluate function that avoids the usage of a g:value instance to get the value of the expression.
See also:
2025-3-14
Function gtk:expression-watch-unwatch (watch)
Arguments:
watch -- a gtk:expression-watch instance to release
Details:
Stops watching an expression that was established with the gtk:expression-watch function.
See also:
2025-3-14
Function gtk:property-expression-new (gtype expression property)
Arguments:
gtype -- a g:type-t type ID to expect for the this type
expression -- a gtk:expression instance to evaluate to get the object to query or nil to query the this object
property -- a string with the name of the property
Returns:
The new gtk:expression instance.
Details:
Creates an expression that looks up a property via the given expression or the this argument when expression is nil. If the resulting object conforms to gtype, its property named property will be queried. Otherwise, this expression's evaluation will fail. The given gtype must have a property with property.
See also:
2025-3-14
Function gtk:property-expression-new-for-pspec (expression pspec)
Arguments:
expression -- a gtk:expression instance to evaluate to get the object to query or nil to query the this object
pspec -- a g:param-spec instance for the property to query
Returns:
The new gtk:expression instance.
Details:
Creates an expression that looks up a property via the given expression or the this argument when the expression argument is nil. If the resulting object conforms to the type of this, its property specified by pspec will be queried. Otherwise, the evaluation of the expression will fail.
See also:
2025-3-14
Function gtk:property-expression-expression (expression)
Arguments:
expression -- a property gtk:expression instance
Returns:
The object gtk:expression instance.
Details:
Gets the expression specifying the object of a property expression.
See also:
2025-3-14
Function gtk:property-expression-pspec (expression)
Arguments:
expression -- a gtk:expression instance
Returns:
The g:param-spec instance.
Details:
Gets the g:param-spec instance specifying the property of a property expression.
See also:
2025-3-14
Function gtk:constant-expression-new (gtype value)
Arguments:
gtype -- a g:type-t type ID
value -- a value corresponding to gtype
Returns:
The new gtk:expression instance.
Details:
Creates an expression that evaluates to the object given by the arguments.
Examples:
(let ((expr (gtk:constant-expression-new "gint" 100)))
  (prog1
    (g:value-int (gtk:constant-expression-value expr))
    (gtk:expression-unref expr)))
=> 100    
See also:
2025-3-14
Function gtk:constant-expression-new-for-value (value)
Arguments:
value -- a g:value instance
Returns:
The new gtk:expression instance.
Details:
Creates an expression that always evaluates to the given value.
See also:
2025-3-14
Function gtk:constant-expression-value (expression)
Arguments:
expression -- a constant gtk:expression instance
Returns:
The g:value value.
Details:
Gets the value that a constant expression evaluates to.
See also:
2025-3-14
Function gtk:object-expression-new (object)
Arguments:
object -- a g:object instance to watch
Returns:
The new gtk:expression instance.
Details:
Creates an expression evaluating to the given object with a weak reference. Once the object is disposed, it will fail to evaluate. This expression is meant to break reference cycles. If you want to keep a reference to object, use the gtk:constant-expression-new function.
See also:
2025-3-14
Function gtk:object-expression-object (expression)
Arguments:
expression -- a gtk:expression instance for an object
Returns:
The g:object instance, or nil.
Details:
Gets the object that the expression evaluates to.
See also:
2025-3-14
Function gtk:value-expression (value)
Syntax:
(gtk:value-expression value) => expression
(setf (gtk:value-expression value) expression)
Arguments:
value -- a g:value instance initialized with the gtk:expression type
expression -- a gtk:expression instance
Details:
The gtk:value-expression function retrieves the gtk:expression instance stored inside the given value. The (setf gtk:value-expression) function stores the given gtk:expression instance inside value. The g:value instance will acquire a reference to the expression.
See also:
2025-3-14

GtkFilter

GEnum gtk:filter-match
Declaration:
(gobject:define-genum "GtkFilterMatch" filter-match
  (:export t
   :type-initializer "gtk_filter_match_get_type")
  :some
  :none
  :all)  
Values:
:some
The filter matches some items, the gtk:filter-match function may return true or false.
:none
The filter does not match any item, the gtk:filter-match function will always return false.
:all
The filter matches all items, the gtk:filter-match function will always return true.
Details:
Describes the known strictness of a filter. Note that for filters where the strictness is not known, the :some value is always an acceptable value, even if a filter does match all or no items.
See also:
2024-9-27
GEnum gtk:filter-change
Declaration:
(gobject:define-genum "GtkFilterChange" filter-change
  (:export t
   :type-initializer "gtk_filter_change_get_type")
  :different
  :less-strict
  :more-strict)  
Values:
:different
The filter change cannot be described with any of the other enumeration values.
:less-strict
The filter is less strict than it was before. All items that it used to return true for still return true, others now may, too.
:more-strict
The filter is more strict than it was before. All items that it used to return false for still return false, others now may, too.
Details:
Describes changes in a filter in more detail and allows objects using the filter to optimize refiltering items. If you are writing an implementation and are not sure which value to pass, the :different value is always a correct choice.
See also:
2024-9-27
Class gtk:filter
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:filter object describes the filtering to be performed by a gtk:filter-list-model object. The model will use the filter to determine if it should include items or not by calling the gtk:filter-match function for each item and only keeping the ones that the function returns true for.

Filters may change what items they match through their lifetime. In that case, they will emit the "changed" signal to notify that previous filter results are no longer valid and that items should be checked again via the gtk:filter-match function.

GTK provides various pre-made filter implementations for common filtering operations. These filters often include properties that can be linked to various widgets to easily allow searches. However, in particular for large lists or complex search methods, it is also possible to subclass the gtk:filter class and provide one's own filter.
Signal Details:
The "changed" signal
lambda (filter change)    :run-last      
filter
The gtk:filter object.
change
The gtk:filter-change value.
The signal is emitted whenever the filter changed. Users of the filter should then check items again via the gtk:filter-match function. The gtk:filter-list-model object handles this signal automatically. Depending on the change parameter, not all items need to be changed, but only some. Refer to the gtk:filter-change documentation for details.
See also:
2024-10-20
Function gtk:filter-match (filter item)
Arguments:
filter -- a gtk:filter object
item -- a g:object instance for the item to check
Returns:
True if the filter matches the item and a filter model should keep it, false if not.
Details:
Checks if the given item is matched by the filter or not.
Notes:
The C library takes a pointer as an item argument. In the Lisp implementation the function is generalized to take an object. The pointer is retrieved from the object with the gobject:object-pointer function.
See also:
2025-3-13
Function gtk:filter-strictness (filter)
Arguments:
filter -- a gtk:filter object
Returns:
The gtk:filter-match value with the strictness of filter.
Details:
Gets the known strictness of the filter. If the strictness is not known, the :match-some value is returned. The value may change after emission of the "changed" signal. This function is meant purely for optimization purposes, filters can choose to omit implementing it, but the gtk:filter-list-model class uses it.
See also:
2025-3-13
Function gtk:filter-changed (filter change)
Arguments:
filter -- a gtk:filter object
change -- a gtk:filter-change value
Details:
Emits the "changed" signal to notify all users of the filter that the filter changed. Users of the filter should then check items again via the gtk:filter-match function. Depending on the change parameter, not all items need to be changed, but only some. Refer to the gtk:filter-change documentation for details. This function is intended for implementors of gtk:filter subclasses and should not be called from other functions.
See also:
2024-9-27

GtkCustomFilter

Class gtk:custom-filter
Superclasses:
gtk:filter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:custom-filter object is a gtk:filter object that uses a callback to determine whether to include an item or not.
See also:
2024-9-27
Function gtk:custom-filter-new (&optional func)
Arguments:
func -- an optional gtk:custom-filter-func callback function to filter items, the default value is nil
Returns:
The new gtk:custom-filter object.
Details:
Creates a new custom filter using the given func callback function to filter items. If the func argument is nil, the custom filter matches all items. If the custom filter function changes its filtering behavior, the gtk:filter-changed function needs to be called.
See also:
2024-9-27
Callback gtk:custom-filter-func
Syntax:
lambda (item) => result
Arguments:
item -- a g:object instance with the item to be matched
result -- true to keep the item around
Details:
User function that is called to determine if the item should be matched. If the filter matches the item, this function must return true. If the item should be filtered out, false must be returned.
See also:
2024-9-27
Function gtk:custom-filter-set-filter-func (filter &optional func)
Arguments:
filter -- a gtk:custom-filter object
func -- an optional gtk:custom-filter-func callback function to filter items, or the default value nil
Details:
to unset the function Sets (or unsets) the function used for filtering items. If func is nil, the custom filter matches all items. If the custom filter function changes its filtering behavior, the gtk:filter-changed function needs to be called.
See also:
2024-9-27

GtkMultiFilter

Class gtk:multi-filter
Superclasses:
gtk:filter, gio:list-model, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
n-items
The n-items property of type :uint (Read)
The number of items. Since 4.8
Default value: 0
Slot Access Functions:
Details:
The gtk:multi-filter class is the base type that implements support for handling multiple filters.
See also:
2024-9-28
Accessor gtk:multi-filter-item-type (object)
Syntax:
(gtk:multi-filter-item-type object) => gtype
Arguments:
object -- a gtk:multi-filter object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:multi-filter class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:multi-filter-n-items (object)
Syntax:
(gtk:multi-filter-n-items object) => n-items
Arguments:
object -- a gtk:multi-filter object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:multi-filter class.

Since 4.8
See also:
2025-3-13
Function gtk:multi-filter-append (object filter)
Arguments:
object -- a gtk:multi-filter object
filter -- a gtk:filter object to use
Details:
Adds a filter to object to use for matching.
See also:
2024-10-1
Function gtk:multi-filter-remove (object pos)
Arguments:
object -- a gtk:multi-filter object
pos -- an unsigned integer for the position of the filter to remove
Details:
Removes the filter at the given pos from the list of filters used by object. If the pos parameter is larger than the number of filters, nothing happens and the function returns.
See also:
2025-3-13
Class gtk:any-filter
Superclasses:
gtk:multi-filter, gtk:filter, gio:list-model, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:any-filter class is a subclass of the gtk:multi-filter class that matches an item when at least one of its filters matches.
See also:
2024-9-28
Function gtk:any-filter-new ()
Returns:
The new gtk:any-filter object.
Details:
Creates a new empty "any" filter. Use the gtk:multi-filter-append function to add filters to it. This filter matches an item if any of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches no item.
See also:
2024-9-28
Class gtk:every-filter
Superclasses:
gtk:multi-filter, gtk:filter, gio:list-model, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:every-filter class is a subclass of the gtk:multi-filter class that matches an item when each of its filters matches.
See also:
2024-9-28
Function gtk:every-filter-new ()
Returns:
The new gtk:every-filter object.
Details:
Creates a new empty "every" filter. Use the gtk:multi-filter-append function to add filters to it. This filter matches an item if each of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches every item.
See also:
2024-9-28

GtkBoolFilter

Class gtk:bool-filter
Superclasses:
gtk:filter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
expression
The expression property of type gtk:expression (Read / Write)
The boolean expression to evaluate on the item.
invert
The invert property of type :boolean (Read / Write)
Whether the expression result should be inverted.
Default value : false
Returned by:
Slot Access Functions:
Details:
The gtk:bool-filter object is a simple filter that takes a boolean gtk:expression instance to determine whether to include items.
See also:
2025-3-13
Accessor gtk:bool-filter-expression (object)
Syntax:
(gtk:bool-filter-expression object) => expression
(setf (gtk:bool-filter-expression object) expression)
Arguments:
object -- a gtk:bool-filter object
expression -- a gtk:expression instance
Details:
Accessor of the expression slot of the gtk:bool-filter class. The gtk:bool-filter-expression function gets the expression that the filter uses to evaluate if an item should be filtered. The (setf gtk:bool-filter-expression) function sets the expression. The expression must have a "gboolean" value type.
See also:
2024-9-28
Accessor gtk:bool-filter-invert (object)
Syntax:
(gtk:bool-filter-invert object) => invert
(setf (gtk:bool-filter-invert object) invert)
Arguments:
object -- a gtk:bool-filter object
invert -- true to invert
Details:
Accessor of the invert slot of the gtk:bool-filter class. The gtk:bool-filter-invert function returns whether the filter inverts the expression. The (setf gtk:bool-filter-expression) function sets whether the filter should invert the expression.
Notes:
If no expression is set, this function returns the cffi:null-pointer value. To unset the expression for the bool filter, use the cffi:null-pointer value.
See also:
2024-9-28
Function gtk:bool-filter-new (&optional expression)
Arguments:
expression -- a gtk:expression instance or nil for none
Returns:
The new gtk:bool-filter object.
Details:
Creates a new bool filter.
See also:
2024-9-28

GtkStringFilter

GEnum gtk:string-filter-match-mode
Declaration:
(gobject:define-genum "GtkStringFilterMatchMode" string-filter-match-mode
  (:export t
   :type-initializer "gtk_string_filter_match_mode_get_type")
  (:exact 0)
  (:substring 1)
  (:prefix 2))  
Values:
:exact
The search string and text must match exactly.
:substring
The search string must be contained as a substring inside the text.
:prefix
The text must begin with the search string.
Details:
Specifies how search strings are matched inside text.
See also:
2024-9-28
Class gtk:string-filter
Superclasses:
gtk:filter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
expression
The expression property of type gtk:expression (Read / Write)
The expression to evaluate on the item to get a string to compare with.
ignore-case
The ignore-case property of type :boolean (Read / Write)
Whether matching is case sensitive.
Default value: true
match-mode
The match-mode property of type gtk:string-filter-match-mode (Read / Write)
Whether exact matches are necessary or if substrings are allowed.
Default value: :substring
search
The search property of type :string (Read / Write)
The search term.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:string-filter object determines whether to include items by looking at strings and comparing them to a fixed search term. The strings are obtained from the items by evaluating a gtk:expression instance. The gtk:string-filter object has several different modes of comparison - it can match the whole string, just a prefix, or any substring.
See also:
2025-3-13
Accessor gtk:string-filter-expression (object)
Syntax:
(gtk:string-filter-expression object) => expression
(setf (gtk:string-filter-expression object) expression)
Arguments:
object -- a gtk:string-filter object
expression -- a gtk:expression instance
Details:
Accessor of the expression slot of the gtk:string-filter class. The gtk:string-filter-expression function gets the expression that the string filter uses to obtain strings from items. The (setf gtk:string-filter-expression) function sets the expression. The expression must have a "gchararray" value type.
See also:
2024-9-28
Accessor gtk:string-filter-ignore-case (object)
Syntax:
(gtk:string-filter-ignore-case object) => ignore
(setf (gtk:stringt-filter-ignore-case object) ignore)
Arguments:
object -- a gtk:string-filter object
ignore -- true to ignore case
Details:
Accessor of the ignore-case slot of the gtk:string-filter class. The gtk:string-filter-ignore-case function returns whether the filter ignores case differences. The (setf gtk:string-filter-ignore-case) function sets whether the filter ignores case differences.
See also:
2024-9-28
Accessor gtk:string-filter-match-mode (object)
Syntax:
(gtk:string-filter-match-mode object) => mode
(setf (gtk:stringt-filter-match-mode object) mode)
Arguments:
object -- a gtk:string-filter object
Details:
Accessor of the match-mode slot of the gtk:string-filter class. The gtk:string-filter-match-mode function returns the match mode that the filter is using. The (setf gtk:string-filter-match-mode) function sets the match mode for the filter.
See also:
2024-9-28
Syntax:
(gtk:string-filter-search object) => search
(setf (gtk:stringt-filter-search object) search)
Arguments:
object -- a gtk:string-filter object
search -- a string to search for or nil to clear the search
Details:
Accessor of the search slot of the gtk:string-filter class. The gtk:string-filter-search function gets the search string. The (setf gtk:string-filter-search) function sets the string to search for.
See also:
2024-9-28
Function gtk:string-filter-new (&optional expression)
Arguments:
expression -- a gtk:expression instance for the expression to evaluate or nil for none
Returns:
The new gtk:string-filter object.
Details:
Creates a new string filter. You will want to set up the filter by providing a string to search for and by providing a property to look up on the item.
See also:
2025-3-13

GtkFileFilter

Class gtk:file-filter
Superclasses:
gtk:filter, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
mime-types
The mime-types property of type :string (Write / Construct only)
The MIME types that this filter matches. Note: This property is not accessible from the Lisp side. Since 4.10
name
The name property of type :string (Read / Write)
The human-readable name of the filter. This is the name that will be displayed in the file selector user interface if there is a selectable list of filters.
Default value: nil
patterns
The patterns property of type :string (Write / Construct only)
The patterns that this filter matches. Note: This property is not accessible from the Lisp side. Since 4.10
suffixes
The suffixes property of type :string (Write / Construct only)
The suffixes that this filter matches. Note: This property is not accessible from the Lisp side. Since 4.10
Returned by:
Slot Access Functions:
Details:
The gtk:file-filter object can be used to restrict the files being shown in a gtk:file-chooser widget. Files can be filtered based on their name with the gtk:file-filter-add-pattern function or on their MIME type with the gtk:file-filter-add-mime-type function.

Filtering by MIME types handles aliasing and subclassing of MIME types. For example, a filter for text/plain also matches a file with MIME type application/rtf, since application/rtf is a subclass of text/plain. Note that the gtk:file-filter object allows wildcards for the subtype of a MIME type, so you can, for example, filter for image/*.

Normally, file filters are used by adding them to a gtk:file-chooser widget, see the gtk:file-chooser-add-filter function, but it is also possible to manually use a file filter on any gtk:filter-list-model object containing g:file-info objects.
GtkFileFilter as GtkBuildable:
The gtk:file-filter implementation of the gtk:buildable interface supports adding rules using the <mime-types> and <patterns> elements and listing the rules within. Specifying a <mime-type> or <pattern> element has the same effect as calling the gtk:file-filter-add-mime-type or gtk:file-filter-add-pattern functions.
Examples:
An example of a UI definition fragment specifying gtk:file-filter rules:
<object class="GtkFileFilter">
  <property name="name" translatable="yes">Text and Images</property>
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
  </patterns>
  <suffixes>
    <suffix>png</suffix>
  </suffixes>
</object>    
See also:
2025-3-13
Accessor gtk:file-filter-name (object)
Syntax:
(gtk:file-filter-name object) => name
(setf (gtk:file-filter-name object) name)
Arguments:
object -- a gtk:file-filter object
name -- a string for the human-readable name for the filter, or nil to remove any existing name
Details:
Accessor of the name slot of the gtk:file-filter class. The gtk:file-filter-name function gets the human-readable name for the file filter. The (setf gtk:file-filter-name) function sets a human-readable name. This is the name that will be displayed in the file chooser if there is a selectable list of filters.
See also:
2025-3-13
Function gtk:file-filter-new ()
Returns:
The new gtk:file-filter object.
Details:
Creates a new file filter with no rules added to it. Such a file filter does not accept any files, so is not particularly useful until you add rules with the gtk:file-filter-add-mime-type, the gtk:file-filter-add-pattern, or gtk:file-filter-add-pixbuf-formats functions.
Examples:
To create a file filter that accepts any file, use:
(let ((filter (gtk:file-filter-new)))
  (gtk:file-filter-add-pattern filter "*")
  ... )    
See also:
2025-3-13
Function gtk:file-filter-new-from-gvariant (variant)
Arguments:
variant -- a g:variant parameter of a{sv} type
Returns:
The new gtk:file-filter object.
Details:
Deserialize a file filter from a a{sv} variant in the format produced by the gtk:file-filter-to-gvariant function.
See also:
2025-3-13
Function gtk:file-filter-add-mime-type (filter mime-type)
Arguments:
filter -- a gtk:file-filter object
mime-type -- a string for the name of the MIME type
Details:
Adds a rule allowing a given MIME type to the file filter.
See also:
2025-3-13
Function gtk:file-filter-add-pattern (filter pattern)
Arguments:
filter -- a gtk:file-filter object
pattern -- a string for a shell style glob
Details:
Adds a rule allowing a shell style glob to a file filter. Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on other platforms, it does not.
See also:
2025-3-13
Function gtk:file-filter-add-pixbuf-formats (filter)
Arguments:
filter -- a gtk:file-filter object
Details:
Adds a rule allowing image files in the formats supported by the gdk-pixbuf:pixbuf object. This is equivalent to calling the gtk:file-filter-add-mime-type function for all the supported MIME types.
See also:
2025-3-13
Function gtk:file-filter-add-suffix (filter suffix)
Arguments:
filter -- a gtk:file-filter object
suffix -- a string for the filename suffix to match
Details:
Adds a suffix match rule to a filter. This is similar to adding a match for the *.suffix pattern. In contrast to pattern matches, suffix matches are always case-insensitive.

Since 4.4
See also:
2025-3-13
Function gtk:file-filter-attributes (filter)
Arguments:
filter -- a gtk:file-filter object
Returns:
The list of strings with the attributes.
Details:
Gets the attributes that need to be filled in for the g:file-info object passed to this file filter. This function will not typically be used by applications. It is intended principally for use in the implementation of the gtk:file-chooser widget.
See also:
2025-3-13
Function gtk:file-filter-to-gvariant (filter)
Arguments:
filter -- a gtk:file-filter object
Returns:
The new g:variant parameter.
Details:
Serialize a file filter to a a{sv} variant.
See also:
2025-3-13

GtkSorter

GEnum gtk:sorter-order
Declaration:
(gobject:define-genum "GtkSorterOrder" sorter-order
  (:export t
   :type-initializer "gtk_sorter_order_get_type")
  (:partial 0)
  (:none 1)
  (:total 2))  
Values:
:partial
A partial order, any value of the gtk:ordering enumeration is possible.
:none
No order, all elements are considered equal. The gtk:sorter-compare function will only return the :equal value of the gtk:ordering enumeration.
:total
A total order, the gtk:sorter-compare function will only return the :equal value of the gtk:ordering enumeration if an item is compared with itself. Two different items will never cause this value to be returned.
Details:
Describes the type of order that a gtk:sorter object may describe.
See also:
2024-10-18
GEnum gtk:sorter-change
Declaration:
(gobject:define-genum "GtkSorterChange" sorter-change
  (:export t
   :type-initializer "gtk_sorter_change_get_type")
  (:different 0)
  (:inverted 1)
  (:less-strict 2)
  (:more-strict 3))  
Values:
:different
The sorter change cannot be described by any of the other enumeration values.
:inverted
The sort order was inverted. Comparisons that returned the :smaller value now return the :larger value of the gtk:ordering enumeration and vice versa. Other comparisons return the same values as before.
:less-strict
The sorter is less strict. Comparisons may now return the :equal value of the gtk:ordering enumeration that did not do so before.
:more-strict
The sorter is more strict. Comparisons that did return the :equal value of the gtk:ordering enumeration may not do so anymore.
Details:
Describes changes in a sorter in more detail and allows users to optimize resorting.
See also:
2024-10-18
Class gtk:sorter
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:sorter object is the way to describe sorting criteria. Its primary user is the gtk:sort-list-model object. The model will use a sorter to determine the order in which its items should appear by calling the gtk:sorter-compare function for pairs of items.

Sorters may change their sorting behavior through their lifetime. In that case, they will emit the "changed" signal to notify that the sort order is no longer valid and should be updated by calling the gtk:sorter-compare function again.

GTK provides various pre-made sorter implementations for common sorting operations. The gtk:column-view widget has built-in support for sorting lists via the sorter property, where the user can change the sorting by clicking on list headers.

Of course, in particular for large lists, it is also possible to subclass the gtk:sorter object and provide one's own sorter.
Signal Details:
The "changed" signal
lambda (sorter change)    :run-last      
sorter
The gtk:sorter object.
change
How the sorter changed as a gtk:sorter-change value.
This signal is emitted whenever the sorter changed. Users of the sorter should then update the sort order again via the gtk:sorter-compare function. The gtk:sort-list-model object handles this signal automatically. Depending on the change parameter, it may be possible to update the sort order without a full resorting. Refer to the gtk:sorter-change documentation for details.
See also:
2024-10-18
Function gtk:sorter-compare (sorter obj1 obj2)
Arguments:
sorter -- a gtk:sorter object
obj1 -- a g:object instance for the first item to compare
obj2 -- a g:object instance for the second item to compare
Returns:
The gtk:ordering value with the :equal value if obj1 = obj2, the :smaller value if obj1 < obj2, the :larger value if obj1 > obj2.
Details:
Compares two given objects according to the sort order implemented by the sorter.

Sorters implement a partial order:
  • It is reflexive, that is a = a.
  • It is antisymmetric, that is if a < b and b < a, then a = b.
  • It is transitive, that is given any 3 objects with a ≤ b and b ≤ c, then a ≤ c.
The sorter may signal it conforms to additional constraints via the return value of the gtk:sorter-order function.
See also:
2025-3-14
Function gtk:sorter-order (sorter)
Arguments:
sorter -- a gtk:sorter object
Returns:
The gtk:sorter-order value.
Details:
Gets the order that sorter conforms to. See the gtk:sorter-order enumeration for details of the possible return values. This function is intended to allow optimizations.
See also:
2024-10-18
Function gtk:sorter-changed (sorter change)
Arguments:
sorter -- a gtk:sorter object
change -- a gtk:sorter-change value
Details:
Emits the "changed" signal to notify all users of the sorter that it has changed. Users of the sorter should then update the sort order via the gtk:sorter-compare function.

Depending on the change parameter, it may be possible to update the sort order without a full resorting. Refer to the gtk:sorter-change documentation for details.

This function is intended for implementors of gtk:sorter subclasses and should not be called from other functions.
See also:
2024-10-18
Function gtk:ordering-from-cmpfunc (result)
Arguments:
result -- an integer for the result of a comparison function
Returns:
The gtk:ordering value.
Details:
Converts the result of a g:compare-data-func function to a gtk:ordering value.

Since 4.2
Examples:
(mapcar #'gtk:ordering-from-cmpfunc '(-1 0 +1))
=> (:SMALLER :EQUAL :LARGER)    
See also:
2025-3-14

GtkCustomSorter

Class gtk:custom-sorter
Superclasses:
gtk:sorter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:custom-sorter object is a gtk:sorter implementation that sorts via a g:compare-data-func callback function.
See also:
2025-3-14
Function gtk:custom-sorter-new (&optional func)
Arguments:
func -- a g:compare-data-func callback function to use for sorting
Returns:
The new gtk:custom-sorter object.
Details:
Creates a new custom sorter that works by calling the func callback function to compare objects. If func is nil, all objects are considered equal.
See also:
2025-3-14
Function gtk:custom-sorter-set-sort-func (sorter func)
Arguments:
sorter -- a gtk:custom-sorter object
func -- a g:compare-data-func callback function
Details:
Sets (or unsets) the callback function used for sorting items. If func is nil, all items are considered equal. If the sort function changes its sorting behavior, the gtk:sorter-changed function needs to be called.
See also:
2025-3-14

GtkMultiSorter

Class gtk:multi-sorter
Superclasses:
gtk:sorter, gio:list-model, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:multi-sorter object combines multiple sorters by trying them in turn. If the first sorter compares two items as equal, the second is tried next, and so on.
See also:
2024-12-22
Accessor gtk:multi-sorter-item-type (object)
Syntax:
(gtk:multi-sorter-item-type object) => gtype
Arguments:
object -- a gtk:multi-sorter object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:multi-sorter class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:multi-sorter-n-items (object)
Syntax:
(gtk:multi-sorter-n-items object) => n-items
Arguments:
object -- a gtk:multi-sorter object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:multi-sorter class.

Since 4.8
See also:
2025-3-14
Function gtk:multi-sorter-new ()
Returns:
The new gtk:multi-sorter object.
Details:
Creates a new multi sorter. This sorter compares items by trying each of the sorters in turn, until one returns non-zero. In particular, if no sorter has been added to it, it will always compare items as equal.
See also:
2024-10-21
Function gtk:multi-sorter-append (sorter other)
Arguments:
sorter -- a gtk:multi-sorter object
other -- another gtk:sorter object to add
Details:
Add other to sorter to use for sorting at the end. The sorter object will consult all existing sorters before it will sort with the given other.
See also:
2024-10-24
Function gtk:multi-sorter-remove (object pos)
Arguments:
sorter -- a gtk:multi-sorter object
pos -- an unsigned integer for the position of the sorter to remove
Details:
Removes the sorter at the given pos from the list of sorter used by sorter. If the pos parameter is larger than the number of sorters, nothing happens.
See also:
2025-3-14

GtkStringSorter

GEnum gtk:collation
Declaration:
(gobject:define-genum "GtkCollation" collation
  (:export t
   :type-initializer "gtk_collation_get_type")
  (:none 0)
  (:unicode 1)
  (:filename 2))  
Values:
:none
Do not do any collation.
:unicode
Use the g_utf8_collate_key() function.
:filename
Use the g_utf8_collate_key_for_filename() function.
Details:
Describes how a gtk:string-sorter object turns strings into sort keys to compare them. Note that the result of sorting will in general depend on the current locale unless the mode is :none.

Since 4.10
See also:
2024-10-24
Class gtk:string-sorter
Superclasses:
gtk:sorter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
collation
The collation property of type gtk:collation (Read / Write)
The collation method to use for sorting. The :none value is useful when the expression already returns collation keys, or strings that need to be compared byte-by-byte. The default value, :unicode, compares strings according to the Unicode collation algorithm. Since 4.10
Default value: :unicode
expression
The expression property of type gtk:expression (Read / Write)
The expression to evaluate on items to get a string to compare with.
ignore-case
The ignore-case property of type :boolean (Read / Write)
Whether matching is case sensitive.
Default value: true
Returned by:
Details:
The gtk:string-sorter object is a gtk:sorter implementation that compares strings. It does the comparison in a linguistically correct way using the current locale by normalizing Unicode strings and possibly case-folding them before performing the comparison.

To obtain the strings to compare, this sorter evaluates a gtk:expression instance.
See also:
2024-10-24
Accessor gtk:string-sorter-collation (object)
Syntax:
(gtk:string-sorter-collation object) => collation
(setf (gtk:string-sorter-collation object) collation)
Arguments:
object -- a gtk:string-sorter object
collation -- a gtk:collation value
Details:
Accessor of the collation slot of the gtk:string-sorter class. The gtk:string-sorter-collation function gets which collation method the sorter uses. The (setf gtk:string-sorter-collation) function sets the collation method.

Since 4.10
See also:
2024-10-24
Accessor gtk:string-sorter-expression (object)
Syntax:
(gtk:string-sorter-expression object) => expression
(setf (gtk:string-sorter-expression object) expression)
Arguments:
object -- a gtk:string-sorter object
expression -- a gtk:expression instance, or (cffi:null-pointer)
Details:
Accessor of the expression slot of the gtk:string-sorter class. The gtk:string-sorter-expression function gets the expression that is evaluated to obtain strings from items. The (setf gtk:string-sorter-expression) function sets the expression. The expression must have the "gchararray" type.
See also:
2024-10-24
Accessor gtk:string-sorter-ignore-case (object)
Syntax:
(gtk:string-sorter-ignore-case object) => setting
(setf (gtk:string-sorter-ignore-case object) setting)
Arguments:
object -- a gtk:string-sorter object
setting -- true to ignore case differences
Details:
Accessor of the ignore-case slot of the gtk:string-sorter class. The gtk:string-sorter-ignore-case function gets whether the sorter ignores case differences. The (setf gtk:string-sorter-ignore-case) function sets the property.
See also:
2024-10-24
Function gtk:string-sorter-new (expression)
Arguments:
expression -- a gtk:expression instance to evaluate
Returns:
The new gtk:string-sorter object.
Details:
Creates a new string sorter that compares items using the given expression. Unless an expression is set on it, this sorter will always compare items as invalid.
See also:
2024-10-24

GtkNumericSorter

Class gtk:numeric-sorter
Superclasses:
gtk:sorter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
expression
The expression property of type gtk:expression (Read / Write)
The expression to evaluate on items to get a number to compare with.
sort-order
The sort-order property of type gtk:sort-type (Read / Write)
Whether the sorter will sort smaller numbers first.
Default value: :ascending
Returned by:
Slot Access Functions:
Details:
The gtk:numeric-sorter object is a gtk:sorter implementation that compares numbers. To obtain the numbers to compare, this sorter evaluates a gtk:expression instance.
See also:
2024-10-24
Accessor gtk:numeric-sorter-expression (object)
Syntax:
(gtk:numeric-sorter-expression object) => expression
(setf (gtk:numeric-sorter-expression object) expression)
Arguments:
object -- a gtk:numeric-sorter object
expression -- a gtk:expression instance, or nil
Details:
Accessor of the expression slot of the gtk:numeric-sorter class. The gtk:numeric-sorter-expression function gets the expression that is evaluated to obtain numbers from items. The (setf gtk:numeric-sorter-expression) function sets the expression.

Unless an expression is set on object, the sorter will always compare items as invalid. The expression must have a return type that can be compared numerically.
See also:
2024-10-24
Accessor gtk:numeric-sorter-sort-order (object)
Syntax:
(gtk:numeric-sorter-sort-order object) => order
(setf (gtk:numeric-sorter-sort-order object) order)
Arguments:
object -- a gtk:numeric-sorter object
order -- a gtk:sort-type value
Details:
Accessor of the sort-order slot of the gtk:numeric-sorter class. The gtk:numeric-sorter-sort-order function gets whether this sorter will sort smaller numbers first. The (setf gtk:numeric-sorter-sort-order) function sets the property.
See also:
2024-10-24
Function gtk:numeric-sorter-new (expression)
Arguments:
expression -- a gtk:expression instance to evalute
Returns:
The new gtk:numeric-sorter object.
Details:
Creates a new numeric sorter using the given expression. Smaller numbers will be sorted first. You can call the gtk:numeric-sorter-sort-order function to change this.
See also:
2024-10-24

GtkSelectionModel

Interface gtk:selection-model
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:selection-model interface is an interface that extends the g:list-model interface by adding support for selections. This support is then used by widgets using list models to add the ability to select and unselect various items.

GTK provides default implementations of the most common selection modes such as the gtk:single-selection implementation, so you will only need to implement this interface if you want detailed control about how selections should be handled.

The gtk:selection-model object supports a single boolean per item indicating if an item is selected or not. This can be queried via the gtk:selection-model-is-selected function. When the selected state of one or more items changes, the model will emit the "selection-changed" signal by calling the gtk:selection-model-selection-changed function. The positions given in that signal may have their selection state changed, though that is not a requirement. If new items added to the model via the "items-changed" signal are selected or not is up to the implementation.

Note that items added via the "items-changed" signal may already be selected and no "selection-changed" signal will be emitted for them. So to track which items are selected, it is necessary to listen to both signals.

Additionally, the interface can expose functionality to select and unselect items. If these functions are implemented, list widgets will allow users to select and unselect items. However, the gtk:selection-model implementations are free to only implement them partially or not at all. In that case the widgets will not support the unimplemented operations.

When selecting or unselecting is supported by a model, the return values of the selection functions do not indicate if selection or unselection happened. They are only meant to indicate complete failure, like when this mode of selecting is not supported by the model.

Selections may happen asynchronously, so the only reliable way to find out when an item was selected is to listen to the signals that indicate selection.
Signal Details:
The "selection-changed" signal
lambda (model pos n-items)    :run-last      
model
The gtk:selection-model object.
pos
The unsigned integer with the first item that may have changed.
n-items
The unsigned integer with the number of items with changes.
Emitted when the selection state of some of the items in model changes. Note that this signal does not specify the new selection state of the items, they need to be queried manually. It is also not necessary for a model to change the selection state of any of the items in the selection model, though it would be rather useless to emit such a signal.
See also:
2025-3-17
Function gtk:selection-model-is-selected (model pos)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the position of the item to query
Returns:
True if the item is selected.
Details:
Checks if the given item is selected.
See also:
2025-3-17
Function gtk:selection-model-selection (model)
Syntax:
(gtk:selection-model-selection model) => selected
(setf (gtk:selection-model-selection model mask) selected)
Arguments:
model -- a gtk:selection-model object
selected -- a gtk:bitset instance specifying the items which are selected or should be selected or unselected
mask -- a gtk:bitset instance specifying which items should be updated
Details:
The gtk:selection-model-selection function gets the bitset containing all currently selected items in the model. This function may be slow, so if you are only interested in single item, consider using the gtk:selection-model-is-selected function or if you are only interested in a few consider the gtk:selection-model-selection-in-range function.

The (setf gtk:selection-model-selection) function is the most advanced selection updating method that allows the most fine-grained control over selection changes. If you can, you should try the simpler versions, as implementations are more likely to implement support for those.

Requests that the selection state of all positions set in mask be updated to the respective value in the selected bitmask. In pseudocode, it would look something like this:
for (i = 0; i < n_items; i++)
  {
    // don't change values not in the mask
    if (!gtk_bitset_contains (mask, i))
      continue;

if (gtk_bitset_contains (selected, i)) select_item (i); else unselect_item (i); }

gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items);
The mask and selected parameters must not be modified. They may refer to the same bitset, which would mean that every item in the set should be selected.
See also:
2024-12-2
Function gtk:selection-model-selection-in-range (model pos n-items)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the start of the queried range
n-items -- an unsigned integer for the number of items in the queried range
Returns:
The gtk:bitset instance that matches the selection state for the given state with all other values being undefined. The bitset must not be modified.
Details:
Gets a bitset containing a set where the values in the range [pos, pos + n-items) match the selected state of the items in that range. All values outside that range are undefined.

This function is an optimization for the gtk:selection-model-selection function when you are only interested in part of the model's selected state. A common use case is in response to the "selection-changed" signal.
See also:
2025-3-17
Function gtk:selection-model-select-item (model pos unselect)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the position to select an item in the model
unselect -- a boolean whether previously selected items should be unselected
Returns:
True if this action was supported and no fallback should be tried. This does not mean the item was selected.
Details:
Requests to select an item in the model.
See also:
2025-3-17
Function gtk:selection-model-unselect-item (model pos)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the position of the item to unselect
Returns:
True if this action was supported and no fallback should be tried. This does not mean the item was unselected.
Details:
Requests to unselect an item in the model.
See also:
2025-3-17
Function gtk:selection-model-select-range (model pos n-items unselect)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the first item to select
n-items -- an unsigned integer for the number of items to select
unselect -- a boolean whether previously selected items should be unselected
Returns:
True if this action was supported and no fallback should be tried. This does not mean the range was selected.
Details:
Requests to select a range of items in the model.
See also:
2025-3-17
Function gtk:selection-model-unselect-range (model pos n-items)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the first item to unselect
n-items -- an unsigned integer for the number of items to unselect
Returns:
True if this action was supported and no fallback should be tried. This does not mean the range was unselected.
Details:
Requests to unselect a range of items in the model.
See also:
2025-3-17
Function gtk:selection-model-select-all (model)
Arguments:
model -- a gtk:selection-model object
Returns:
True if this action was supported and no fallback should be tried. This does not mean that all items are now selected.
Details:
Requests to select all items in the model.
See also:
2025-3-17
Function gtk:selection-model-unselect-all (model)
Arguments:
model -- a gtk:selection-model object
Returns:
True if this action was supported and no fallback should be tried. This does not mean that all items are now unselected.
Details:
Requests to unselect all items in the model.
See also:
2025-3-17
Function gtk:selection-model-selection-changed (model pos n-items)
Arguments:
model -- a gtk:selection-model object
pos -- an unsigned integer for the first changed item
n-items -- an unsigned integer for the number of changed items
Details:
Helper function for implementations of the gtk:selection-model class. Call this when the selection changes to emit the "selection-changed" signal.
See also:
2025-3-17

GtkNoSelection

Class gtk:no-selection
Superclasses:
gtk:selection-model, gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being managed.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Details:
The gtk:no-selection class is an implementation of the gtk:selection-model interface that does not allow selecting anything. This model is meant to be used as a simple wrapper to g:list-model objects when a gtk:selection-model object is required. The gtk:no-selection object passes through sections from the underlying model.
See also:
2024-12-22
Accessor gtk:no-selection-item-type (object)
Syntax:
(gtk:no-selection-item-type object) => gtype
Arguments:
object -- a gtk:no-selection object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:no-selection class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:no-selection-model (object)
Syntax:
(gtk:no-selection-model object) => model
(setf (gtk:no-selection-model object) model)
Arguments:
object -- a gtk:no-selection object
model -- a g:list-model object to wrap
Details:
Accessor of the model slot of the gtk:no-selection class. The gtk:no-selection-model function gets the model that object is wrapping. The (setf gtk:no-selection-model) function sets the model that object should wrap. If model is nil, this model will be empty.
See also:
2025-3-17
Accessor gtk:no-selection-n-items (object)
Syntax:
(gtk:no-selection-n-items object) => n-items
Arguments:
object -- a gtk:no-selection object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:no-selection class.

Since 4.8
See also:
2025-3-17
Function gtk:no-selection-new (&optional model)
Arguments:
model -- an optional g:list-model object to manage, or the default nil value
Returns:
The new gtk:no-selection object.
Details:
Creates a new selection to handle the given model.
See also:
2024-11-27

GtkSingleSelection

Constant gtk:+invalid-list-position+
Initial Value:
4294967295
Details:
The value used to refer to a guaranteed invalid position in a g:list-model object. This value may be returned from some functions, others may accept it as input. Its interpretation may differ for different functions.

Refer to each function's documentation for if this value is allowed and what it does.
See also:
2025-3-17
Class gtk:single-selection
Superclasses:
gtk:selection-model, gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
autoselect
The autoselect property of type :boolean (Read / Write)
Whether the selection will always select an item.
Default value: true
can-unselect
The can-unselect property of type :boolean (Read / Write)
Whether unselecting the selected item is allowed.
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being managed.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
selected
The selected property of type :uint (Read / Write)
The position of the selected item.
Default value: gtk:+invalid-list-position+
selected-item
The selected-item property of type g:object (Read)
The selected item.
Returned by:
Details:
The gtk:single-selection class is an implementation of the gtk:selection-model interface that allows selecting a single element. It is the default selection method used by list widgets in GTK.

Note that the selection is *persistent* -- if the selected item is removed and re-added in the same "items-changed" signal emission, it stays selected. In particular, this means that changing the sort order of an underlying sort model will preserve the selection.
See also:
2024-12-22
Accessor gtk:single-selection-autoselect (object)
Syntax:
(gtk:single-selection-autoselect object) => autoselect
(setf (gtk:single-selection-autoselect object) autoselect)
Arguments:
object -- a gtk:single-selection object
autoselect -- true if autoselect is enabled
Details:
Accessor of the autoselect slot of the gtk:single-selection class. The gtk:single-selection-autoselect function checks if autoselect has been enabled or disabled. The (setf gtk:single-selection-autoselect) function sets the property.

If autoselect is true, object will enforce that an item is always selected. It will select a new item when the currently selected item is deleted and it will disallow unselecting the current item.
See also:
2025-3-17
Accessor gtk:single-selection-can-unselect (object)
Syntax:
(gtk:single-selection-can-unselect object) => setting
(setf (gtk:single-selection-can-unselect object) setting)
Arguments:
object -- a gtk:single-selection object
setting -- true to allow unselecting
Details:
Accessor of the can-unselect slot of the gtk:single-selection class. If true, unselecting the current item is supported. Note that setting autoselect will cause the unselecting to not work, so it practically makes no sense to set both at the same time the same time.
See also:
2025-3-17
Accessor gtk:single-selection-item-type (object)
Syntax:
(gtk:single-selection-item-type object) => gtype
Arguments:
object -- a gtk:single-selection object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:single-selection class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-11-22
Accessor gtk:single-selection-model (object)
Syntax:
(gtk:single-selection-model object) => model
(setf (gtk:single-selection-model object) model)
Arguments:
object -- a gtk:single-selection object
model -- a g:list-model object to wrap
Details:
Accessor of the model slot of the gtk:single-selection class. The gtk:single-selection-model function gets the model that object is wrapping. The (setf gtk:single-selection-model) function sets the model that object should wrap. If model is nil, object will be empty.
See also:
2025-3-17
Accessor gtk:single-selection-n-items (object)
Syntax:
(gtk:single-selection-n-items object) => n-items
Arguments:
object -- a gtk:single-selection object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:single-selection class.
See also:
g:single-selection
g:list-model-n-items
2025-3-17
Accessor gtk:single-selection-selected (object)
Syntax:
(gtk:single-selection-selected object) => pos
(setf (gtk:single-selection-selected object) pos)
Arguments:
object -- a gtk:single-selection object
pos -- an unsigned integer for the item to select or the gtk:+invalid-list-position+ value
Details:
Accessor of the selected slot of the gtk:single-selection class. The gtk:single-selection-selected function gets the position of the selected item. If no item is selected, the gtk:+invalid-list-position+ value is returned. The (setf gtk:single-selection-selected) function selects the item at the given pos.

If the list does not have an item at pos or the gtk:+invalid-list-position+ value is given, the behavior depends on the value of the autoselect property. If it is set, no change will occur and the old item will stay selected. If it is unset, the selection will be unset and no item will be selected.
See also:
2025-3-17
Accessor gtk:single-selection-selected-item (object)
Syntax:
(gtk:single-selection-selected object) => item
Arguments:
object -- a gtk:single-selection object
item -- a g:object instance for the selected item
Details:
Accessor of the selected-item slot of the gtk:single-selection class. The gtk:single-selection-selected-item function gets the selected item. If no item is selected, nil ist returned.
See also:
2025-3-17
Function gtk:single-selection-new (&optional model)
Arguments:
model -- an optional g:list-model object to manage, the default is nil
Returns:
The new gtk:single-selection object.
Details:
Creates a new selection to handle model.
See also:
2025-3-17

GtkMultiSelection

Class gtk:multi-selection
Superclasses:
gtk:selection-model, gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being managed by this selection.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:multi-selection class is an implementation of the gtk:selection-model interface that allows selecting multiple elements.
See also:
2024-12-2
Accessor gtk:multi-selection-item-type (object)
Syntax:
(gtk:multi-selection-item-type object) => gtype
Arguments:
object -- a gtk:multi-selection object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:multi-selection class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:multi-selection-model (object)
Syntax:
(gtk:multi-selection-model object) => model
(setf (gtk:multi-selection-model object) model)
Arguments:
object -- a gtk:multi-selection object
model -- a g:list-model object to wrap
Details:
Accessor of the model slot of the gtk:multi-selection class. The gtk:multi-selection-model function returns the underlying model of object. The (setf gtk:multi-selection-model) function sets the model that object should wrap. If model is nil, object will be empty.
See also:
2024-12-2
Accessor gtk:multi-selection-n-items (object)
Syntax:
(gtk:multi-selection-n-items object) => n-items
Arguments:
object -- a gtk:multi-selection object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:multi-selection class.
See also:
g:multi-selection
g:list-model-n-items
2025-3-17
Function gtk:multi-selection-new (&optional model)
Arguments:
model -- a g:list-model object to manage, or the nil default value
Returns:
The new gtk:multi-selection object.
Details:
Creates a new selection to handle model.
See also:
2024-12-2

GtkSectionModel

Interface gtk:section-model
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:section-model interface is an interface that adds support for sections to list models. A gtk:section-model object groups successive items into so-called sections. List widgets like the gtk:list-view and gtk:grid-view widget then allow displaying section headers for these sections by installing a header factory.

Many GTK list models support sections inherently, or they pass through the sections of a model they are wrapping.

When the section groupings of a model change, the model will emit the "sections-changed" signal by calling the gtk:section-model-sections-changed function. All sections in the given range then need to be queried again. The "items-changed" signal has the same effect, all sections in that range are invalidated, too.

Since 4.12
Signals:
The "sections-changed" signal
lambda (model pos n-items)    :run-last      
model
The gtk:section-model object that emitted the signal.
pos
The unsigned integer with the first item that may have changed.
n-items
The unsigned integer with the number of items with changes.
Emitted when the start-of-section state of some of the items in model changes. Note that this signal does not specify the new section state of the items, they need to be queried manually. It is also not necessary for a model to change the section state of any of the items in the section model, though it would be rather useless to emit such a signal. The "items-changed" signal of the g:list-model class implies the effect of the "sections-changed" signal for all the items it covers.
See also:
2024-11-29
Function gtk:section-model-section (model pos)
Syntax:
(gtk:section-model-section model pos) => start, end
Arguments:
model -- a gtk:section-model object
pos -- an unsigned integer for the position of the item to query
start -- an unsigned integer for the position of the first item in the section
end -- an unsigned integer for the position of the first item not part of the section anymore
Details:
Query the section that covers the given position. The number of items in the section can be computed by end - start.

If the position is larger than the number of items, a single range from n-items to G_MAXUINT will be returned.

Since 4.12
See also:
2025-3-17
Function gtk:section-model-sections-changed (model pos n-items)
Arguments:
model -- a gtk:section-model object
pos -- an unsigned integer for the first item hat may have changed
n-items -- an unsigned integer for the number of items with changes
Details:
Emits the "sections-changed" signal on model.

Since 4.12
See also:
2025-3-17

GtkFilterListModel

Class gtk:filter-list-model
Superclasses:
gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
filter
The filter property of type gtk:filter (Read / Write)
The filter for the model.
incremental
The incremental property of type :boolean (Read / Write)
Whether the model should filter items incrementally.
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being filtered.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
pending
The pending property of type :uint (Read)
The number of items not yet filtered.
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:filter-list-model object is a list model that filters the elements of the underlying model according to a gtk:filter object. It hides some elements from the other model according to criteria given by a gtk:filter object.

The model can be set up to do incremental searching, so that filtering long lists does not block the UI. See the gtk:filter-list-model-incremental function for details.
See also:
2025-3-26
Accessor gtk:filter-list-model-filter (object)
Syntax:
(gtk:filter-list-model-filter object) => filter
(setf (gtk:filter-list-model-filter object) filter)
Arguments:
object -- a gtk:filter-list-model object
filter -- a gtk:filter object to use or nil to not filter items
Details:
Accessor of the filter slot of the gtk:filter-list-model class. The gtk:filter-list-model-filter function gets the filter currently set. The (setf gtk:filter-list-model-model) function sets the filter used to filter items.
See also:
2025-3-18
Accessor gtk:filter-list-model-incremental (object)
Syntax:
(gtk:filter-list-model-incremental object) => incremental
(setf (gtk:filter-list-model-incremental object) incremental)
Arguments:
object -- a gtk:filter-list-model object
incremental -- true if incremental filtering is enabled
Details:
Accessor of the incremental slot of the gtk:filter-list-model class. The gtk:filter-list-model-incremental function returns whether incremental filtering was enabled. The (setf gtk:filter-list-model-incremental) function sets incremental filtering.

When incremental filtering is enabled, the gtk:filter-list-model object will not run filters immediately, but will instead queue an idle handler that incrementally filters the items and adds them to the list. This of course means that items are not instantly added to the list, but only appear incrementally.

When your filter blocks the UI while filtering, you might consider turning this on. Depending on your model and filters, this may become interesting around 10,000 to 100,000 items. By default, incremental filtering is disabled.

See the gtk:filter-list-model-pending function for progress information about an ongoing incremental filtering operation.
See also:
2025-3-18
Accessor gtk:filter-list-model-item-type (object)
Syntax:
(gtk:filter-list-model-item-type object) => gtype
Arguments:
object -- a gtk:filter-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:filter-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2025-3-18
Accessor gtk:filter-list-model-model (object)
Syntax:
(gtk:filter-list-model-model object) => model
(setf (gtk:filter-list-model-model object) model)
Arguments:
object -- a gtk:filter-list-model object
model -- a g:list-model object that gets filtered
Details:
Accessor of the model slot of the gtk:filter-list-model class. The gtk:filter-list-model-model function gets the model currently filtered or nil if none. The (setf gtk:filter-list-model-model) function sets the model to be filtered.

Note that GTK makes no effort to ensure that model conforms to the item type of object. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match.
See also:
2025-3-18
Accessor gtk:filter-list-model-n-items (object)
Syntax:
(gtk:filter-list-model-n-items object) => n-items
Arguments:
object -- a gtk:filter-list-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:filter-list-model class.
See also:
2025-3-18
Accessor gtk:filter-list-model-pending (object)
Syntax:
(gtk:filter-list-model-pending object) => pending
Arguments:
object -- a gtk:filter-list-model object
pending -- an unsigned integer for the number of items not yet filtered.
Details:
Accessor of the pending slot of the gtk:filter-list-model class. The gtk:filter-list-model-pending function returns the number of items that have not been filtered yet.

You can use this value to check if object is busy filtering by comparing the return value to 0 or you can compute the percentage of the filter remaining by dividing the return value by the total number of items in the underlying model:
(let ((percentage (/ (gtk:filter-list-model-pending object)
                     (gtk:filter-list-model-n-items object))))
  ... )  
If no filter operation is ongoing - in particular when the incremental property is false - this function returns 0.
See also:
2025-3-18
Function gtk:filter-list-model-new (model filter)
Arguments:
model -- a g:list-model object to sort, or nil
filter -- a gtk:filter object or nil to not filter items
Returns:
The new gtk:filter-list-model object.
Details:
Creates a new gtk:filter-list-model object that will filter model using the given filter.
See also:
2025-3-18

GtkFlattenListModel

Class gtk:flatten-list-model
Superclasses:
gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being flattened.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:flatten-list-model object is a list model that takes a list model containing list models and flattens it into a single model. Another term for this is concatenation. The gtk:flatten-list-model object takes a list of lists and concatenates them into a single list.
See also:
2024-12-9
Accessor gtk:flatten-list-model-item-type (object)
Syntax:
(gtk:flatten-list-model-item-type object) => gtype
Arguments:
object -- a gtk:flatten-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:flatten-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:flatten-list-model-model (object)
Syntax:
(gtk:flatten-list-model-model object) => model
(setf (gtk:flatten-list-model-model object) model)
Arguments:
object -- a gtk:flatten-list-model object
model -- a g:list-model object that gets flattened
Details:
Accessor of the model slot of the gtk:flatten-list-model class. The gtk:flatten-list-model-model function gets the model currently flattened or nil if none. The (setf gtk:flatten-list-model-model) function sets the model to be flattened.
See also:
2024-12-9
Accessor gtk:flatten-list-model-n-items (object)
Syntax:
(gtk:flatten-list-model-n-items object) => n-items
Arguments:
object -- a gtk:flatten-list-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:flatten-list-model class.
See also:
2024-12-9
Function gtk:flatten-list-model-new (model)
Arguments:
model -- a g:list-model object to be flattened
Returns:
The new gtk:flatten-list-model object.
Details:
Creates a new gtk:flatten-list-model object that flattens model.
See also:
2024-12-9
Function gtk:flatten-list-model-model-for-item (model pos)
Arguments:
model -- a gtk:flatten-list-model object
pos -- an unsigned integer for a position
Returns:
The g:list-model object containing the item at pos.
Details:
Returns the model containing the item at the given pos.
See also:
2025-3-18

GtkMapListModel

Class gtk:map-list-model
Superclasses:
gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
has-map
The has-map property of type :boolean (Read)
Whether a map function is set for this model.
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write / Construct only)
The model being mapped.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:map-list-model object is a list model that takes a list model and maps the items in that model to different items according to a gtk:map-list-model-map-func callback function.
Examples:
Create a list of gtk:event-controller objects.
(let* (...
       (widgets (gtk:widget-observe-children widget))
       (controllers (gtk:map-list-model-new widgets
                           (lambda (item)
                             (gtk:widget-observe-controllers item))))
       (model (gtk:flatten-list-model-new controllers)))
  ... )    
The gtk:map-list-model object will attempt to discard the mapped objects as soon as they are no longer needed and recreate them if necessary.
See also:
2024-12-15
Accessor gtk:map-list-model-has-map (object)
Syntax:
(gtk:map-list-model-has-map object) => setting
Arguments:
object -- a gtk:map-list-model object
setting -- a boolean whether a map function is set for this model
Details:
Accessor of the has-map slot of the gtk:map-list-model class. The gtk:map-list-model-has-map function checks if a map function is currently set on object.
See also:
2024-12-15
Accessor gtk:map-list-model-item-type (object)
Syntax:
(gtk:map-list-model-item-type object) => gtype
Arguments:
object -- a gtk:map-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:map-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:map-list-model-model (object)
Syntax:
(gtk:map-list-model-model object) => model
Arguments:
object -- a gtk:map-list-model object
model -- a g:list-model object that gets mapped
Details:
Accessor of the model slot of the gtk:map-list-model class. The gtk:map-list-model-model function gets the model that is currently being mapped or nil if none.

GTK makes no effort to ensure that the model conforms to the item type expected by the map function. It assumes that the caller knows what they are doing and have set up an appropriate map function.
See also:
2024-12-15
Accessor gtk:map-list-model-n-items (object)
Syntax:
(gtk:map-list-model-n-items object) => n-items
Arguments:
object -- a gtk:map-list-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:map-list-model class.
See also:
g:map-list-model
g:list-model-n-items
2025-3-18
Function gtk:map-list-model-new (model func)
Arguments:
model -- a g:list-model object to map or nil for none
func -- a gtk:map-list-model-map-func callback function to map items or nil
Returns:
The new gtk:map-list-model object.
Details:
Creates a new gtk:map-list-model object for the given arguments.
See also:
2024-12-15
Callback gtk:map-list-model-map-func
Syntax:
lambda (item) => result
Arguments:
item -- a g:object instance for the item to map
result -- a g:object instance for the item to map to, this function may not return nil
Details:
User function that is called to map an item of the original model to an item expected by the map model. The returned items must conform to the item type of the model they are used with.
See also:
2025-3-18
Function gtk:map-list-model-set-map-func (model func)
Arguments:
model -- a gtk:map-list-model object
func -- a gtk:map-list-model-map-func callback function to map items or nil
Details:
Sets the function used to map items. The function will be called whenever an item needs to be mapped and must return the item to use for the given input item.

Note that the gtk:map-list-model object may call this function multiple times on the same item, because it may delete items it does not need anymore.

GTK makes no effort to ensure that func conforms to the item type of model. It assumes that the caller knows what they are doing and the map function returns items of the appropriate type.
See also:
2024-12-15

GtkSliceListModel

Class gtk:slice-list-model
Superclasses:
gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The child model to take slice from.
n-items
The n-items property of type :uint (Read / Write)
The number of items.
Default value: 0
offset
The offset property of type :int (Read / Write)
The offset of slice.
Default value: 0
size
The size property of type :uint (Read / Write)
The maximum size of slice.
Default value: 10
Returned by:
Slot Access Functions:
Details:
The gtk:slice-list-model object is a list model that takes a list model and presents a slice of that model. This is useful when implementing paging by setting the size to the number of elements per page and updating the offset whenever a different page is opened. The gtk:slice-list-model object passes through sections from the underlying model.
See also:
2024-12-15
Accessor gtk:slice-list-model-item-type (object)
Syntax:
(gtk:slice-list-model-item-type object) => gtype
Arguments:
object -- a gtk:slice-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:slice-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:slice-list-model-model (object)
Syntax:
(gtk:slice-list-model-model object) => model
(setf (gtk:slice-list-model-model object) model)
Arguments:
object -- a gtk:slice-list-model object
model -- a g:list-model object to be sliced
Details:
Accessor of the model slot of the gtk:slice-list-model class. The gtk:slice-list-model-model function gets the model that is currently being used or nil if none. The (setf gtk:slice-list-model-model) function sets the model to show a slice of. The item type of model must conform to the item type of object.
See also:
2024-12-15
Accessor gtk:slice-list-model-n-items (object)
Syntax:
(gtk:slice-list-model-n-items object) => n-items
Arguments:
object -- a gtk:slice-list-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:slice-list-model class.
See also:
g:slice-list-model
g:list-model-n-items
2025-3-18
Accessor gtk:slice-list-model-offset (object)
Syntax:
(gtk:slice-list-model-offset object) => offset
(setf (gtk:slice-list-model-offset object) offset)
Arguments:
object -- a gtk:slice-list-model object
offset -- an integer for the offset
Details:
Accessor of the offset slot of the gtk:slice-list-model class. The gtk:slice-list-model-offset function gets the offset. The (setf gtk:slice-list-model-offset) function sets the offset into the original model for this slice. If the offset is too large for the sliced model, object will end up empty.
See also:
2025-3-18
Accessor gtk:slice-list-model-size (object)
Syntax:
(gtk:slice-list-model-size object) => size
(setf (gtk:slice-list-model-size object) size)
Arguments:
object -- a gtk:slice-list-model object
size -- an unsigned integer for the size
Details:
Accessor of the size slot of the gtk:slice-list-model class. The gtk:slice-list-model-size function gets the maximum size. The (setf gtk:slice-list-model-size) function sets the maximum size. object will never have more items than size. It can however have fewer items if the offset is too large or the model sliced from does not have enough items.
See also:
2025-3-18
Function gtk:slice-list-model-new (model offset size)
Arguments:
model -- a g:list-model object to use, or nil
offset -- an unsigned integer for the offset of the slize
size -- an unsigned integer for the maximum size of the slize
Returns:
The new gtk:slice-list-model object.
Details:
Creates a new slice model that presents the slice from offset to offset + size out of the given model.
See also:
2025-3-18

GtkSortListModel

Class gtk:sort-list-model
Superclasses:
gio:list-model, gtk:section-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
incremental
The incremental property of type :boolean (Read / Write)
Whether the model should sort items incrementally.
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being sorted.
n-items
The n-items property of type :uint (Read / Write)
The number of items.
Default value: 0
pending
The pending property of type :uint (Read / Write)
The estimate of unsorted items remaining.
Default value: 0
section-sorter
The section-sorter property of type gtk:sorter (Read / Write)
The section sorter for this model, if one is set.
sorter
The sorter property of type gtk:sorter (Read / Write)
The sorter for this model.
Returned by:
Slot Access Functions:
Details:
The gtk:sort-list-model object is a g:list-model object that sorts the elements of an underlying model according to a gtk:sorter object.

The model is a stable sort. If two items compare equal according to the sorter, the one that appears first in the original model will also appear first after sorting. Note that if you change the sorter, the previous order will have no influence on the new order. If you want that, consider using a gtk:multi-sorter object and appending the previous sorter to it.

The model can be set up to do incremental sorting, so that sorting long lists does not block the UI. See the gtk:sort-list-model-incremental function for details.

The gtk:sort-list-model object is a generic model and because of that it cannot take advantage of any external knowledge when sorting. If you run into performance issues with the gtk:sort-list-model object, it is strongly recommended that you write your own sorting list model.

The gtk:sort-list-model object allows sorting the items into sections. It implements the gtk:section-model interface and when the section-sorter is set, it will sort all items with that sorter and items comparing equal with it will be put into the same section. The sorter property will then be used to sort items inside their sections.
See also:
2024-12-15
Accessor gtk:sort-list-model-incremental (object)
Syntax:
(gtk:sort-list-model-incremental object) => incremental
(setf (gtk:sort-list-model-incremental object) incremental)
Arguments:
object -- a gtk:sort-list-model object
incremental -- a boolean whether incremental sorting is enabled
Details:
Accessor of the incremental slot of the gtk:sort-list-model class. The gtk:sort-list-model-incremental function returns whether incremental sorting was enabled. The (setf gtk:sort-list-model-incremental) function sets the sort model to do an incremental sort.

When incremental sorting is enabled, the sort list model will not do a complete sort immediately, but will instead queue an idle handler that incrementally sorts the items towards their correct position. This of course means that items do not instantly appear in the right place. It also means that the total sorting time is a lot slower.

When your filter blocks the UI while sorting, you might consider turning this on. Depending on your model and sorters, this may become interesting around 10.000 to 100.000 items.

By default, incremental sorting is disabled. See the gtk:sort-list-model-pending function for progress information about an ongoing incremental sorting operation.
See also:
2024-12-15
Accessor gtk:sort-list-model-item-type (object)
Syntax:
(gtk:sort-list-model-item-type object) => gtype
Arguments:
object -- a gtk:sort-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:sort-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:sort-list-model-model (object)
Syntax:
(gtk:sort-list-model-model object) => model
(setf (gtk:sort-list-model-model object) model)
Arguments:
object -- a gtk:sort-list-model object
model -- a g:list-model object to be sorted
Details:
Accessor of the model slot of the gtk:sort-list-model class. The gtk:sort-list-model-model function gets the model currently sorted or nil if none. The (setf gtk:sort-list-model-model) function sets the model to be sorted. The item type of model must conform to the item type of object.
See also:
2024-12-15
Accessor gtk:sort-list-model-n-items (object)
Syntax:
(gtk:sort-list-model-n-items object) => n-items
Arguments:
object -- a gtk:sort-list-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:sort-list-model class.
See also:
g:sort-list-model
g:list-model-n-items
2025-3-18
Accessor gtk:sort-list-model-pending (object)
Syntax:
(gtk:sort-list-model-pending object) => pending
Arguments:
object -- a gtk:sort-list-model object
pending -- an unsigned integer for the estimate of unsorted items remaning
Details:
Accessor of the pending slot of the gtk:sort-list-model class. The gtk:sort-list-model-pending estimates progress of an ongoing sorting operation.

The estimate is the number of items that would still need to be sorted to finish the sorting operation if this was a linear algorithm. So this number is not related to how many items are already correctly sorted.

If you want to estimate the progress, you can use code like this:
(let* ((pending (gtk:sort-list-model-pending model))
       (store (gtk:sort-list-model-model model))
       (progress (- 1.0 (/ pending
                           (max 1 (g:list-model-n-items store))))))
  ... )  
If no sort operation is ongoing, in particular when the incremental property is false, this function returns 0.
See also:
2025-3-18
Accessor gtk:sort-list-model-section-sorter (object)
Syntax:
(gtk:sort-list-model-section-sorter object) => sorter
(setf (gtk:sort-list-model-section-sorter object) sorter)
Arguments:
object -- a gtk:sort-list-model object
sorter -- a gtk:sorter object to sort object with
Details:
Accessor of the section-sorter slot of the gtk:sort-list-model class. The gtk:sort-list-model-section-sorter function gets the section sorter that is used to sort items of the list model into sections. The (setf gtk:sort-list-model-section-sorter) function sets a new section sorter.
See also:
2024-12-15
Accessor gtk:sort-list-model-sorter (object)
Syntax:
(gtk:sort-list-model-sorter object) => sorter
(setf (gtk:sort-list-model-sorter object) sorter)
Arguments:
object -- a gtk:sort-list-model object
sorter -- a gtk:sorter object to sort object with
Details:
Accessor of the sorter slot of the gtk:sort-list-model class. The gtk:sort-list-model-sorter function gets the sorter that is used to sort object. The (setf gtk:sort-list-model-sorter) function sets a new sorter.
See also:
2024-12-15
Function gtk:sort-list-model-new (model sorter)
Arguments:
model -- a g:list-model object, or nil
sorter -- a gtk:sorter object to sort model with, or nil
Returns:
The new gtk:sort-list-model object.
Details:
Creates a new sort list model that uses the sorter to sort model.
See also:
2024-12-15

GtkSelectionFilterModel

Class gtk:selection-filter-model
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read / Write)
The model being filtered.
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Details:
The gtk:selection-filter-model class is a list model that presents the selected items in a gtk:selection-model as its own list model.
See also:
2024-12-15
Accessor gtk:selection-filter-model-item-type (object)
Syntax:
(gtk:selection-filter-model-item-type object) => gtype
Arguments:
object -- a gtk:selection-filter-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:selection-filter-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:selection-filter-model-model (object)
Syntax:
(gtk:selection-filter-model-model object) => model
(setf (gtk:selection-filter-model-model object) model)
Arguments:
object -- a gtk:selection-filter-model object
model -- a g:list-model object to wrap
Details:
Accessor of the model slot of the gtk:selection-filter-model class. The gtk:selection-filter-model-model function gets the model currently filtered or nil if none. The (setf gtk:selection-filter-model-model) function sets the model to be filtered.

Note that GTK makes no effort to ensure that model conforms to the item type of object. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match.
See also:
2024-12-15
Accessor gtk:selection-filter-model-n-items (object)
Syntax:
(gtk:selection-filter-model-n-items object) => n-items
Arguments:
object -- a gtk:selection-filter-model object
n-items -- an unsigned integer for the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:selection-filter-model class.
See also:
2025-3-18
Function gtk:selection-filter-model-new (model)
Arguments:
model -- a gtk:selection-model object to filter, or nil
Returns:
Details:
Creates a new gtk:selection-filter-model object that will include the selected items from the underlying selection model.
See also:
2024-12-15

GtkBookmarkList

Class gtk:bookmark-list
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
attributes
The attributes property of type :string (Read / Write)
The attributes to query.
Default value: nil
filename
The filename property of type :string (Read / Write / Construct only)
The bookmark file to load.
Default value: $XDG_USER_DATA/recently-used.xbel
io-priority
The io-priority property of type :int (Read / Write)
The priority used when loading.
Allowed values: >= -2147483647
Default value: g:+priority-default+
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
loading
The loading property of type :boolean (Read)
True if files are being loaded.
Default value: false
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:bookmark-list class is a list model that wraps the GBookmarkFile class. It presents a g:list-model object and fills it asynchronously with the g:file-info objects returned from that function.

The g:file-info objects in the list have some attributes in the recent namespace added: recent::private (boolean) and recent:applications (stringv).
See also:
2024-12-15
Accessor gtk:bookmark-list-attributes (object)
Syntax:
(gtk:bookmark-list-attributes object) => attributes
(setf (gtk:bookmark-list-attributes object) attributes)
Arguments:
object -- a gtk:bookmark-list object
attributes -- a string with the attributes
Details:
Accessor of the attributes slot of the gtk:bookmark-list class. The gtk:bookmark-list-attributes function gets the attributes queried on the children. The (setf gtk:bookmark-list-attributes) function sets the attributes to be enumerated and starts the enumeration.

If the attributes argument is nil, no attributes will be queried, but a list of g:file-info objects will still be created.
See also:
2024-12-15
Accessor gtk:bookmark-list-filename (object)
Syntax:
(gtk:bookmark-list-filename object) => filename
Arguments:
object -- a gtk:bookmark-list object
filename -- a string with the filename of the .xbel file
Details:
Accessor of the filename slot of the gtk:bookmark-list class. The gtk:bookmark-list-filename function returns the filename of the bookmark file that the bookmark list is loading.
Notes:
The default location of the bookmark file is $XDG_USER_DATA/recently-used.xbel. This filename is the default value for the filename property. You can get the path of the location with
(cffi:foreign-funcall "g_get_user_data_dir" :string)    
See also:
2024-12-15
Accessor gtk:bookmark-list-io-priority (object)
Syntax:
(gtk:bookmark-list-io-priority object) => priority
(setf (gtk:bookmark-list-io-priority object) priority)
Arguments:
object -- a gtk:bookmark-list object
priority -- an integer with the IO priority to use
Details:
Accessor of the io-priority slot of the gtk:bookmark-list class. The gtk:bookmark-list-io-priority function gets the IO priority. The (setf gtk:bookmark-list-io-priority) function sets the IO priority to use while loading files. The default IO priority is the g:+priority-default+ value.
See also:
2024-12-15
Accessor gtk:bookmark-list-item-type (object)
Syntax:
(gtk:bookmark-list-item-type object) => gtype
Arguments:
object -- a gtk:bookmark-list object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:bookmark-list class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:bookmark-list-loading (object)
Syntax:
(gtk:bookmark-list-loading object) => loading
Arguments:
object -- a gtk:bookmark-list object
loading -- true if files are being loaded
Details:
Accessor of the loading slot of the gtk:bookmark-list class.
See also:
2024-12-15
Accessor gtk:bookmark-list-n-items (object)
Syntax:
(gtk:bookmark-list-n-items object) => n-items
Arguments:
object -- a gtk:bookmark-list object
n-items -- an unsigned integer with the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:bookmark-list class.
See also:
2024-12-15
Function gtk:bookmark-list-new (filename attributes)
Arguments:
filename -- a string with the bookmark file to load, or nil
attributes -- a string with the attributes to query
Returns:
The new gtk:bookmark-list object.
Details:
Creates a new bookmark list for the given attributes. If the filename argument is nil the default location at $XDG_USER_DATA/recently-used.xbel is used.
See also:
2024-12-15
Function gtk:bookmark-list-is-loading (model)
Arguments:
model -- a gtk:bookmark-list object
Returns:
True if model is loading.
Details:
Returns true if the files are currently being loaded. Files will be added to model from time to time while loading is going on. The order in which the files are added is undefined and may change in between runs.
Notes:
This function duplicates the gtk:bookmark-list-loading accessor funtion.
See also:
2024-12-15

GtkDirectoryList

Class gtk:directory-list
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
attributes
The attributes property of type :string (Read / Write)
The attributes to query.
Default value: nil
error
The error property of type glib:error (Read)
The error encountered while loading files.
file
The file property of type g:file (Read / Write)
The file to query.
io-priority
The io-priority property of type :int (Read / Write)
The priority used when loading.
Allowed values: >= -2147483647
Default value: g:+priority-default+
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
loading
The loading property of type :boolean (Read)
True if files are being loaded.
Default value: false
monitored
The monitored property of type :boolean (Read / Write)
True if the directory is monitored for changed.
Default value: true
n-items
The n-items property of type :uint (Read / Write)
The number of items. Since 4.8
Default value: 0
Details:
The gtk:directory-list class is a list model that wraps the requested information from the g_file_enumerate_children_async() function. It presents a g:list-model object and fills it asynchronously with the g:file-info objects returned from that function. Enumeration will start automatically when the file property is set.

While the gtk:directory-list object is being filled, the loading property will be set to true. You can listen to that property if you want to show information like a gtk:spinner widget or a "Loading..." text.

If loading fails at any point, the error property will be set to give more indication about the failure.

The g:file-info objects returned from a gtk:directory-list object have the "standard::file" attribute set to the g:file object they refer to. This way you can get the file that is referred to in the same way you would via the g_file_enumerator_child() function. This means you do not need access to the gtk:directory-list object but can access the g:file object directly from the g:file-info object when operating with a gtk:list-view widget or similar.
See also:
2024-12-15
Accessor gtk:directory-list-attributes (object)
Syntax:
(gtk:directory-list-attributes object) => attributes
(setf (gtk:directory-list-attributes object) attributes)
Arguments:
object -- a gtk:directory-list object
attributes -- a string with the attributes
Details:
Accessor of the attributes slot of the gtk:directory-list class. The gtk:directory-list-attributes function gets the attributes queried on the children. The (setf gtk:directory-list-attributes) function sets the attributes to be enumerated and starts the enumeration.

If the attributes argument is nil, no attributes will be queried, but a list of g:file-info objects will still be created.
See also:
2024-12-15
Accessor gtk:directory-list-error (object)
Syntax:
(gtk:directory-list-error object) => error
Arguments:
object -- a gtk:directory-list object
error -- a glib:error instance with the loading error or nil if loading finished successfully
Details:
Accessor of the error slot of the gtk:directory-list class. The gtk:directory-list-error function gets the loading error, if any.

If an error occurs during the loading process, the loading process will finish and this property allows querying the error that happened. This error will persist until a file is loaded again. An error being set does not mean that no files were loaded, and all successfully queried files will remain in the list.
See also:
2024-12-15
Accessor gtk:directory-list-file (object)
Syntax:
(gtk:directory-list-file object) => file
(setf (gtk:directory-list-file object) file)
Arguments:
object -- a gtk:directory-list object
file -- a g:file object to be enumerated
Details:
Accessor of the file slot of the gtk:directory-list class. The gtk:directory-list-file function gets the file whose children are currently enumerated. The (setf gtk:directory-list-file) function sets the file to be enumerated and starts the enumeration. If the file argument is nil, the result will be an empty list.
See also:
2024-12-15
Accessor gtk:directory-list-io-priority (object)
Syntax:
(gtk:directory-list-io-priority object) => priority
(setf (gtk:directory-list-io-priority object) priority)
Arguments:
object -- a gtk:directory-list object
priority -- an integer with the IO priority to use
Details:
Accessor of the io-priority slot of the gtk:directory-list class. The gtk:directory-list-io-priority function gets the IO priority. The (setf gtk:directory-list-io-priority) function sets the IO priority to use while loading files.

Setting the priority while object is loading will reprioritize the ongoing load as soon as possible. The default IO priority is the g:+priority-default+ value, which is higher than the GTK redraw priority. If you are loading a lot of directories in parallel, lowering it to something like the g:+priority-default-idle+ value may increase responsiveness.
See also:
2024-12-15
Accessor gtk:directory-list-item-type (object)
Syntax:
(gtk:directory-list-item-type object) => gtype
Arguments:
object -- a gtk:directory-list object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:directory-list class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:directory-list-loading (object)
Syntax:
(gtk:directory-list-loading object) => loading
Arguments:
object -- a gtk:directory-list object
loading -- true if files are being loaded
Details:
Accessor of the loading slot of the gtk:directory-list class.
See also:
2024-12-15
Accessor gtk:directory-list-monitored (object)
Syntax:
(gtk:directory-list-monitored object) => monitored
(setf (gtk:directory-list-monitored object) monitored)
Arguments:
object -- a gtk:directory-list object
monitored -- true to monitor the directory for changes
Details:
Accessor of the monitored slot of the gtk:directory-list class. The gtk:directory-list-monitored function returns whether the directory list is monitoring the directory for changes. The (setf gtk:directory-list-monitored) function sets whether the directory list will monitor the directory for changes. If monitoring is enabled, the "items-changed" signal will be emitted when the directory contents change.

When monitoring is turned on after the initial creation of the directory list, the directory is reloaded to avoid missing files that appeared between the initial loading and when monitoring was turned on.
See also:
2024-12-15
Accessor gtk:directory-list-n-items (object)
Syntax:
(gtk:directory-list-n-items object) => n-items
Arguments:
object -- a gtk:directory-list object
n-items -- an unsigned integer with the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:directory-list class.
See also:
2024-12-15
Function gtk:directory-list-new (attributes file)
Arguments:
attributes -- a string with the attributes to query with
file -- a g:file object to query
Returns:
The gtk:directory-list object.
Details:
Creates a new directory list querying the given file with the given attributes.
See also:
2024-12-15
Function gtk:directory-list-is-loading (model)
Arguments:
model -- a gtk:directory-list object
Returns:
True if model is loading.
Details:
Returns true if the children enumeration is currently in progress. Files will be added to model from time to time while loading is going on. The order in which the files are added is undefined and may change in between runs.
See also:
2024-12-15

GtkStringList

Class gtk:string-object
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
string
The string property of type :string (Read)
The string.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:string-object class is the type of items in a gtk:string-list object. A gtk:string-object object is a wrapper around a string. It has a string property that can be used for property bindings and expressions.
See also:
2025-3-29
Accessor gtk:string-object-string (object)
Syntax:
(gtk:string-object-string object) => string
Arguments:
object -- a gtk:string-object object
string -- a string
Details:
Accessor of the string slot of the gtk:string-object class. The gtk:string-object-string function returns the string contained in a gtk:string-object object.
See also:
2025-3-29
Function gtk:string-object-new (&optional string)
Arguments:
string -- a string to wrap, or nil
Returns:
The new gtk:string-object object.
Details:
Wraps a string in an object for use with a g:list-model object.
Examples:
Create string objects:
(gtk:string-object-new "abcdef") => #<GTK:STRING-OBJECT {1003E79813}>
(gtk:string-object-string *) => "abcdef"
(gtk:string-object-new nil) => #<GTK:STRING-OBJECT {1003E79813}>
(gtk:string-object-string *) => nil    
See also:
2025-3-29
Class gtk:string-list
Superclasses:
gio:list-model, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (read)
The type of items contained in the string list. Since 4.14
n-items
The n-items property of type :uint (read)
The number of items contained in the string list. Since 4.14
Default value: 0
strings
The strings property of type :string (Construct only)
An array of strings. Since 4.10
Note: This property is not readable and not writable. You cannot initialize it in a make-instance method. Therefore, no accessor is exported.
Returned by:
Slot Access Functions:
Details:
The gtk:string-list class is a list model that wraps an array of strings. The objects in the model have a string property. The gtk:string-list object is well-suited for any place where you would typically use a string, but need a list model.
GtkStringList as GtkBuildable:
The gtk:string-list implementation of the gtk:buildable interface supports adding items directly using the <items> element and specifying <item> elements for each item. Each <item> element supports the regular translation attributes "translatable", "context" and "comments". Here is a UI definition fragment specifying a gtk:string-list object:
<object class="GtkStringList">
  <items>
    <item translatable="yes">Factory</item>
    <item translatable="yes">Home</item>
    <item translatable="yes">Subway</item>
  </items>
</object>    
Examples:
Create a list of strings with the external symbols of the GTK library:
(create-list-of-gtk-symbols ()
  (let ((model (gtk:string-list-new '())))
    (do-external-symbols (symbol (find-package "GTK"))
      (gtk:string-list-append model
                              (string-downcase (format nil "~a" symbol))))
    ...))    
See also:
2025-3-29
Accessor gtk:string-list-item-type (object)
Syntax:
(gtk:string-list-item-type object) => type
(setf (gtk:string-list-item-type object) type)
Arguments:
object -- a gtk:string-list object
type -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:string-list class.

Since 4.14
See also:
2025-3-29
Accessor gtk:string-list-n-items (object)
Syntax:
(gtk:string-list-n-items object) => n-items
(setf (gtk:string-list-n-items object) n-items)
Arguments:
object -- a gtk:string-list object
n-items -- an unsigned integer
Details:
Accessor of the n-items slot of the gtk:string-list class.
See also:
2025-3-29
Function gtk:string-list-new (strings)
Arguments:
strings -- a list of strings to put in the model
Returns:
The new gtk:string-list object.
Details:
Creates a new string list with the given strings.
Examples:
(gtk:string-list-new '("Factory" "Home" "Subway"))
=> #<GTK:STRING-LIST {1003E7BC63}>
(gtk:string-list-string * 0) => "Factory"    
See also:
2025-3-29
Function gtk:string-list-append (model string)
Arguments:
model -- a gtk:string-list object
string -- a string to insert
Details:
Appends a string to the string list.
See also:
2025-3-29
Function gtk:string-list-remove (model pos)
Arguments:
model -- a gtk:string-list object
pos -- an unsigned integer for the position of the string that is to be removed
Details:
Removes the string at pos from the string list. The pos argument must be smaller than the current length of the string list.
See also:
2025-3-29
Function gtk:string-list-splice (model pos n additions)
Arguments:
model -- a gtk:string-list object
pos -- an unsigned integer for the position at which to make the change
n -- an unsigned integer for the number of strings to remove
additions -- a list of strings to add
Details:
Changes the string list by removing n strings and adding additions to it. This function is more efficient than the gtk:string-list-append function and the gtk:string-list-remove function, because it only emits the "items-changed" signal once for the change.

The pos and n parameters must be correct, that is, pos + n must be less than or equal to the length of the string list at the time this function is called.
See also:
2025-3-29
Function gtk:string-list-string (model pos)
Arguments:
model -- a gtk:string-list object
pos -- an unsigned integer for the position to get the string for
Returns:
The string at the given position.
Details:
Gets the string that is at position in the string list. If the string list does not contain pos items, nil is returned. This function returns the string. To get the object wrapping it, use the g:list-model-item function.
See also:
2025-3-29

List-based Widgets

List Widget Overview

GTK provides powerful widgets to display and edit lists of data. This document gives an overview over the concepts and how they work together to allow developers to implement lists. Lists are intended to be used whenever developers want to display many objects in roughly the same way.

Lists are perfectly fine to be used for very short list of only 2 or 3 elements, but generally scale to millions of items. Of course, the larger the list grows, the more care needs to be taken to choose the right data structures to keep things running well. Lists are meant to be used with changing data, both with the items itself changing as well as the list adding and removing items. Of course, they work just as well with static data.

Terminology
These terms are used throughout the documentation when talking about lists and you should be aware of what they refer to. These are often generic terms that have a specific meaning in this context.

Views or list widgets are the widgets that hold and manage the lists. Examples of these widgets would be the gtk:list-view or gtk:grid-view widgets.

Views display data from a model. Models implement the g:list-model interface and can be provided in a variety of ways:
  • List model implementations for many specific types of data already exist, for example the gtk:directory-list or gtk:string-list objects.
  • There are generic list model implementations like the g:list-store object that allow building lists of arbitrary objects.
  • Wrapping list models like gtk:filter-list-model or gtk:sort-list-model objects modify, adapt or combine other models.
  • Last but not least, developers are encouraged to create their own g:list-model implementations. The interface is kept deliberately small to make this easy.
The same model can be used in multiple different views and wrapped with multiple different models at once.

The elements in a model are called items. All items are g:object instances. Every item in a model has a position which is the unsigned integer that describes where in the model the item is located. The first item in a model is at position 0. The position of an item can change as other items are added or removed from the model.

It is important to be aware of the difference between items and positions because the mapping from position to item is not permanent, so developers should think about whether they want to track items or positions when working with models. Oftentimes some things are really hard to do one way but very easy the other way.

The other important part of a view is a factory. Each factory is a gtk:list-item-factory implementation that takes care of mapping the items of the model to widgets that can be shown in the view.

The way factories do this is by creating a list item for each item that is currently in use. List items are always gtk:list-item instances. They are only ever created by GTK and provide information about what item they are meant to display.

Different factory implementations use various different methods to allow developers to add the right widgets to list items and to link those widgets with the item managed by the list item. Finding a suitable factory implementation for the data displayed, the programming language and development environment is an important task that can simplify setting up the view tremendously.

Views support selections via a selection model. A selection model is an implementation of the gtk:selection-model interface on top of the g:list-model interface that allows marking each item in a model as either selected or not selected. Just like regular models, this can be implemented either by implementing the gtk:selection-model interface directly or by wrapping a model with one of the GTK models provided for this purposes, such as the gtk:no-selection or gtk:single-selection models.

The behavior of selection models - that is, which items they allow selecting and what effect this has on other items - is completely up to the selection model. As such, single-selections, multi-selections or sharing selection state between different selection models and/or views is possible. The selection state of an item is exposed in the list item via the selected property.

Views and list items also support activation. Activation means that double clicking or pressing enter while inside a focused row will cause the view to emit a signal such as the GtkListView::activate signal. This provides an easy way to set up lists, but can also be turned off on list items if undesired.

Both selections and activation are supported among other things via widget actions. This allows developers to add widgets to their lists that cause selections to change or to trigger activation via the gtk:actionable interface. For a list of all supported actions see the relevant documentation.

Behind the scenes
While it is not a problem for short lists to instantiate widgets for every item in the model, once lists grow to thousands or millions of elements, this gets less feasible. Because of this, the views only create a limited amount of list items and recycle them by binding them to new items. In general, views try to keep list items available only for the items that can actually be seen on screen.

While this behavior allows views to scale effortlessly to huge lists, it has a few implications for what can be done with views. For example, it is not possible to query a view for a list item used for a certain position - there might not be one and even if there is, that list item might soon be recycled for a new position.

It is also important that developers save state they care about in the item and do not rely on the widgets they created as those widgets can be recycled for a new position at any time causing any state to be lost.

Another important requirement for views is that they need to know which items are not visible so they can be recycled. Views achieve that by implementing the gtk:scrollable interface and expecting to be placed directly into a gtk:scrolled-window widget.

Of course, if you are only using models with few items, this is not important and you can treat views like any other widget. But if you use large lists and your performance suffers, you should be aware of this. Views also allow tuning the number of list items they create such as with the gtk:grid-view-max-columns function, and developers running into performance problems should definitely study the tradeoffs of those and experiment with them.

Choosing the right model
GTK offers a wide variety of wrapping models which change or supplement an existing model (or models) in some way. But when it comes to storing your actual data, there are only a few ready-made choices available: the g:list-store, gtk:string-list, and gtk:directory-list objects.

The g:list-store object is backed by a balanced tree and has performance characteristics that are expected for that data structure. It works reasonably well for dataset sizes in the 1,000,000 range, and can handle insertions and deletions. It uses a cached iterator to make linear access to the items fast.

The gtk:string-list object is not a general store - it can only handle strings. It is backed by an dynamically allocated array and has performance characteristics that are expected for that data structure. The gtk:string-list object is a good fit for any place where you would otherwise use char*[] and works best if the dataset is not very dynamic.

The gtk:directory-list object is a list model that wraps the g_file_enumerate_children_async() function. It presents a g:list-model object and fills it asynchronously with the GFiles returned from that function.

If these models do not fit your use case or scalability requirements, you should make a custom g:list-model implementation. It is a small interface and not very hard to implement.

Displaying trees
While the gtk:tree-view widget provided built-in support for trees, the list widgets, and in particular the g:list-model implementation do not. This was a design choice because the common use case is displaying lists and not trees and it greatly simplifies the API interface provided.

However, GTK provides functionality to make lists look and behave like trees for use cases that require trees. This is achieved by using the gtk:tree-list-model model to flatten a tree into a list. The gtk:tree-expander widget can then be used inside a list item to allow users to expand and collapse rows and provide a similar experience to the gtk:tree-view widget. Developers should refer to those objects’ API reference for more discussion on the topic.

List styles
One of the advantages of the new list widgets over GtkTreeView and cell renderers is that they are styleable using GTK CSS. This provides a lot of flexibility. The themes that ship with GTK provide a few predefined list styles that can be used in many situations.

Figure: Rich list

This rich list style is low density, spacious and uses an outline focus ring. It is suitable for lists of controls, for example, in preference dialogs or settings panels. Use the .rich-list style class.

Figure: Navigation sidebar

The sidebar style of list is medium density, using a full background to indicate focus and selection. Use the .navigation-sidebar style class.

Figure: Data table

The data table style of list is a high density table, similar in style to a traditional tree view. Individual cells can be selectable and editable. Use the .data-table style class.

Sections
List models can optionally group their items into sections, by implementing the gtk:section-model interface. The gtk:list-view widget can display headers for sections, by installing a separate header factory.

Many GTK list models support section inherently, or they pass through the section of a model they are wrapping.

Comparison to GtkTreeView
Developers familiar with GtkTreeView may wonder how this way of doing lists compares to the way they know. This section will try to outline the similarities and differences between the two.

This new approach tries to provide roughly the same functionality as the old approach but often uses a very different way to achieve these goals. The main difference and one of the primary reasons for this new development is that items can be displayed using regular widgets and the separate cell renderer machinery is no longer necessary. This allows all benefits that widgets provide, such as complex layout, animations and CSS styling.

The other big difference is the massive change to the data model. The gtk:tree-model interface was a rather complex interface for a tree data structure. The g:list-model interface is deliberately designed to be a very simple data structure for lists only. See above for how to still do trees with this new model. Another big change is that the new model allows for bulk changes via the GListModel::items-changed signal while the gtk:tree-model interface only allows a single item to change at once. The goal here is of course to encourage implementation of custom list models.

Another consequence of the new model is that it is now easily possible to refer to the contents of a row in the model directly by keeping the item, while the gtk:tree-row-reference implementation was a very slow mechanism to achieve the same. And because the items are real objects, developers can make them emit change signals causing list items and their children to update, which was not possible with the gtk:tree-model implementation.

The selection handling is also different. While selections used to be managed via custom code in each widget, selection state is now meant to be managed by the selection models. In particular this allows for complex use cases with specialized requirements.

Finally here is a quick comparison chart of equivalent functionality to look for when transitioning code:
Old                     New
-------------------------------------------------------
GtkTreeModel            GListModel
GtkTreePath             guint position, GtkTreeListRow
GtkTreeIter             guint position
GtkTreeRowReference     GObject item
GtkListStore            GListStore
GtkTreeStore            GtkTreeListModel, GtkTreeExpander
GtkTreeSelection        GtkSelectionModel
GtkTreeViewColumn       GtkColumnView
GtkTreeView             GtkListView, GtkColumnView
GtkCellView             GtkListItem
GtkComboBox             GtkDropDown
GtkIconView             GtkGridView
GtkTreeSortable         GtkColumnView
GtkTreeModelSort        GtkSortListModel
GtkTreeModelFilter      GtkFilterListModel
GtkCellLayout           GtkListItemFactory
GtkCellArea             GtkWidget
GtkCellRenderer         GtkWidget      

GtkListItem

Class gtk:list-item
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
accessible-description
The accessible-description property of type :string (Read / Write)
The accessible description to set on the list item. Since 4.12
Default value: nil
accessible-label
The accessible-label property of type :string (Read / Write)
The accessible label to set on the list item. Since 4.12
Default value: nil
activatable
The activatable property of type :boolean (Read / Write)
Whether the list item can be activated by the user.
Default value: true
child
The child property of type gtk:widget (Read / Write)
The child widget used for display.
focusable
The focusable property of type :boolean (Read / Write)
Whether the item can be focused with the keyboard. Since 4.12
Default value: true
item
The item property of type g:object (Read)
The displayed item.
position
The position property of type :uint (Read)
The position of the item.
Default Value: gtk:+invalid-list-position+
selectable
The selectable property of type :boolean (Read / Write)
Whether the item can be selected by the user.
Default Value: true
selected
The selected property of type :boolean (Read)
Whether the item is currently selected
Default Value: false
Slot Access Functions:
Details:
The gtk:list-item object is the object that list-handling containers such as the gtk:list-view widget use to represent list items in a g:list-model object.

The gtk:list-item objects are managed by the list widget, with its factory, and cannot be created by applications, but they need to be populated by application code. This is done by calling the gtk:list-item-child function.

The gtk:list-item objects exist in 2 stages:
  1. The unbound stage where the list item is not currently connected to an item in the list. In that case, the item property is set to nil.
  2. The bound stage where the list item references an item from the list. The item property is not nil.
See also:
2025-3-15
Accessor gtk:list-item-accessible-description (object)
Syntax:
(gtk:list-item-accessible-description object) => description
(setf (gtk:list-item-accessible-description object) description)
Arguments:
object -- a gtk:list-item object
description -- a string for the description
Details:
Accessor of the accessible-description slot of the gtk:list-item class. The gtk:list-item-accessible-description function gets the accessible description for the list item. The (setf gtk:list-item-accessible-description) function sets the accessible description. The accessible description may be used by screen readers, for example.

Since 4.12
See also:
2025-3-15
Accessor gtk:list-item-accessible-label (object)
Syntax:
(gtk:list-item-accessible-label object) => label
(setf (gtk:list-item-accessible-label object) label)
Arguments:
object -- a gtk:list-item object
label -- a string for the label
Details:
Accessor of the accessible-label slot of the gtk:list-item class. The gtk:list-item-accessible-label function gets the accessible label for the list item. The (setf gtk:list-item-accessible-label) function sets the accessible label. The accessible label may be used by screen readers, for example.

Since 4.12
See also:
2025-3-15
Accessor gtk:list-item-activatable (object)
Syntax:
(gtk:list-item-activatable object) => activatable
(setf (gtk:list-item-activatable object) activatable)
Arguments:
object -- a gtk:list-item object
activatable -- a boolean whether the list item should be activatable
Details:
Accessor of the activatable slot of the gtk:list-item class. The gtk:list-item-activatable function checks if a list item has been set to be activatable. The (setf gtk:list-item-activatable) function sets object to be activatable.

If a list item is activatable, double-clicking on the list item, using the Return key or calling the gtk:widget-activate function will activate the list item. Activating instructs the containing view to handle activation. The gtk:list-view widget for example will be emitting the "activate" signal.

By default, list items are activatable
See also:
2025-3-15
Accessor gtk:list-item-child (object)
Syntax:
(gtk:list-item-child object) => child
(setf (gtk:list-item-child object) child)
Arguments:
object -- a gtk:list-item object
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:list-item class. The gtk:list-item-child function gets the child widget or nil if none was set. The (setf gtk:list-item-child) function sets the child widget to be used for this list item.

This function is typically called by applications when setting up a list item so that the widget can be reused when binding it multiple times.
See also:
2025-3-15
Accessor gtk:list-item-focusable (object)
Syntax:
(gtk:list-item-focusable object) => focusable
(setf (gtk:list-item-focusable object) focusable)
Arguments:
object -- a gtk:list-item object
focusable -- a boolean whether the list item can be focused
Details:
Accessor of the focusable slot of the gtk:list-item class. The gtk:list-item-focusable function checks if a list item has been set to be focusable. The (setf gtk:list-item-focusable) function sets the list item to be focusable. If a list item is focusable, it can be focused using the keyboard. This works similar to the gtk:widget-focusable function.

Note that if list items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the children of the list item is focusable. By default, list items are focusable.

Since 4.12
See also:
2025-3-15
Accessor gtk:list-item-item (object)
Syntax:
(gtk:list-item-item object) => item
Arguments:
object -- a gtk:list-item object
item -- a g:object instance for the list item displayed
Details:
Accessor of the item slot of the gtk:list-item class. Gets the list item that is currently displayed in the model that object is currently bound to or nil if object is unbound.
See also:
2025-3-15
Accessor gtk:list-item-position (object)
Syntax:
(gtk:list-item-position object) => position
Arguments:
object -- a gtk:list-item object
position -- an unsigned integer for the position of the item.
Details:
Accessor of the position slot of the gtk:list-item class. Gets the position in the model that object currently displays. If object is unbound, the gtk:+invalid-list-position+ value is returned.
See also:
2025-4-11
Accessor gtk:list-item-selectable (object)
Syntax:
(gtk:list-item-selectable object) => selectable
(setf (gtk:list-item-selectable object) selectable)
Arguments:
object -- a gtk:list-item object
selectable -- a boolean whether the item should be selectable
Details:
Accessor of the selectable slot of the gtk:list-item class. The gtk:list-item-selectable function checks if a list item has been set to be selectable. The (setf gtk:list-item-selectable) function sets object to be selectable. If an item is selectable, clicking on the item or using the keyboard will try to select or unselect the item. If this succeeds is up to the model to determine, as it is managing the selected state.

Note that this means that making an item non-selectable has no influence on the selected state at all. A non-selectable item may still be selected.

By default, list items are selectable. When rebinding them to a new item, they will also be reset to be selectable by GTK.
See also:
2025-4-11
Accessor gtk:list-item-selected (object)
Syntax:
(gtk:list-item-selected object) => selected
Arguments:
object -- a gtk:list-item object
selected -- a boolean whether the item is selected
Details:
Accessor of the selected slot of the gtk:list-item class. Checks if the list item is displayed as selected. The selected state is maintained by the container and its list model and cannot be set otherwise.
See also:
2025-3-15

GtkListItemFactory

Class gtk:list-item-factory
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:list-item-factory object creates widgets for the items taken from a g:list-model object. It is one of the core concepts of handling list widgets such as the gtk:list-view or gtk:grid-view widgets.

The gtk:list-item-factory object is tasked with creating widgets for items taken from the model when the views need them and updating them as the items displayed by the view change. A view is usually only able to display anything after both a factory and a model have been set on the view. So it is important that you do not skip this step when setting up your first view.

Because views do not display the whole list at once but only a few items, they only need to maintain a few widgets at a time. They will instruct the gtk:list-item-factory object to create these widgets and bind them to the items that are currently displayed. As the list model changes or the user scrolls to the list, the items will change and the view will instruct the factory to bind the widgets to those new items. The actual widgets used for displaying those widgets is provided by you.

When the factory needs widgets created, it will create a gtk:list-item and hand it to your code to set up a widget for. This list item will provide various properties with information about what item to display and provide you with some opportunities to configure its behavior. See the gtk:list-item documentation for further details.

Various implementations of the gtk:list-item-factory object exist to allow you different ways to provide those widgets. The most common implementations are the gtk:builder-list-item-factory object which takes a gtk:builder UI file and then creates widgets and manages everything automatically from the information in that file and the gtk:signal-list-item-factory object which allows you to connect to signals with your own code and retain full control over how the widgets are setup and managed.

The gtk:list-item-factory object is supposed to be final - that means its behavior should not change and the first widget created from it should behave the same way as the last widget created from it. If you intend to do changes to the behavior, it is recommended that you create a new gtk:list-item-factory object which will allow the views to recreate its widgets.

Once you have chosen your factory and created it, you need to set it on the view widget you want to use it with, such as via the gtk:list-view-factory function. Reusing factories across different views is allowed, but very uncommon.
See also:
2025-3-16

GtkSignalListItemFactory

Class gtk:signal-list-item-factory
Superclasses:
gtk:list-item-factory, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:signal-list-item-factory object is a gtk:list-item-factory object that emits signals to manage list items.

Signals are emitted for every list item in the same order:
  1. The "setup" signal is emitted to set up permanent things on the list item. This usually means constructing the widgets used in the row and adding them to the list item.
  2. The "bind" signal is emitted to bind the item passed via the item property to the widgets that have been created in step 1 or to add item specific widgets. Signals are connected to listen to changes - both to changes in the item to update the widgets or to changes in the widgets to update the item. After this signal has been called, the list item may be shown in a list widget.
  3. The "unbind" signal is emitted to undo everything done in step 2. Usually this means disconnecting signal handlers. Once this signal has been called, the list item will no longer be used in a list widget.
  4. The "bind" and "unbind" signals may be emitted multiple times again to bind the list item for use with new items. By reusing list items, potentially costly setup can be avoided. However, it means code needs to make sure to properly clean up the list item in step 3 so that no information from the previous use leaks into the next use.
  5. The "teardown" signal is emitted to allow undoing the effects of the "setup" signal. After this signal was emitted on a list item, the list item will be destroyed and not be used again.
Note that during the signal emissions, changing properties on the list items passed will not trigger notify signals as the list item’s notifications are frozen. See the g:object-freeze-notify function for details.

For tracking changes in other properties in the list item, the "::notify" signal is recommended. The signal can be connected in the "setup" signal and removed again during the "teardown" signal.
Signal Details:
The "bind" signal
lambda (factory item)    :run-first      
factory
The gtk:signal-list-item-factory object.
item
The gtk:list-item object to bind.
The signal is emitted when a new item has been set on the list item and should be bound for use. After this signal was emitted, the list item might be shown in a gtk:list-view widget or other list widget. The "unbind" signal is the opposite of this signal and can be used to undo everything done in this signal.

The "setup" signal
lambda (factory item)    :run-first      
factory
The gtk:signal-list-item-factory object.
item
The gtk:list-item object to set up.
The signal is emitted when a new list item has been created and needs to be setup for use. It is the first signal emitted for every list item. The "teardown" signal is the opposite of this signal and can be used to undo everything done in this signal.

The "teardown" signal
lambda (factory item)    :run-first      
factory
The gtk:signal-list-item-factory object.
item
The gtk:list-item object to teardown.
The "teardown" signal is emitted when a list item is about to be destroyed. It is the last signal ever emitted for this list item. This signal is the opposite of the "setup" signal and should be used to undo everything done in that signal.

The "unbind" signal
lambda (factory item)    :run-first      
factory
The gtk:signal-list-item-factory object.
item
The gtk:list-item object to unbind.
The signal is emitted when a list item has been removed from use in a list widget and its new item is about to be unset. This signal is the opposite of the "bind" signal and should be used to undo everything done in that signal.
See also:
2025-4-11
Function gtk:signal-list-item-factory-new ()
Returns:
Details:
Creates a new gtk:signal-list-item-factory object. You need to connect signal handlers to the "setup" and "bind" signals before you use it. See the gtk:list-view documentation for a complete example.
See also:
2025-3-16

GtkBuilderListItemFactory

Class gtk:builder-list-item-factory
Superclasses:
gtk:list-item-factory, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
bytes
The bytes property of type g:bytes (Read / Write / Construct Only)
The bytes instance containing the UI definition.
resource
The resource property of type :string (Read / Write / Construct Only)
The resource path containing the UI definition.
Default value: nil
scope
The scope property of type gtk:builder-scope (Read / Write / Construct Only)
The builder scope to use when instantiating list items.
Returned by:
Slot Access Functions:
Details:
The gtk:builder-list-item-factory object is a gtk:list-item-factory object that creates widgets by instantiating gtk:builder UI templates.

The templates must be extending the gtk:list-item object, and typically use gtk:expression instances to obtain data from the items in the model.
Examples:
<interface>
  <template class="GtkListItem">
    <property name="child">
      <object class="GtkLabel">
        <property name="xalign">0</property>
        <binding name="label">
          <lookup name="name" type="SettingsKey">
            <lookup name="item">GtkListItem</lookup>
          </lookup>
        </binding>
      </object>
    </property>
  </template>
</interface>    
See also:
2025-4-11
Accessor gtk:builder-list-item-factory-bytes (object)
Syntax:
(gtk:builder-list-item-factory-bytes object) => bytes
Arguments:
bytes -- a g:bytes instance for the gtk:builder data
Details:
Accessor of the bytes slot of the gtk:builder-list-item-factory class. The gtk:builder-list-item-factory-bytes function gets the data used as the gtk:builder UI template for constructing list items.
See also:
2025-4-11
Accessor gtk:builder-list-item-factory-resource (object)
Syntax:
(gtk:builder-list-item-factory-resource object) => resource
Arguments:
resource -- a string for the path to the resource or nil if none
Details:
Accessor of the resource slot of the gtk:builder-list-item-factory class. If the data references a resource, gets the path of that resource.
See also:
2025-4-11
Accessor gtk:builder-list-item-factory-scope (object)
Syntax:
(gtk:builder-list-item-factory-scope object) => scope
Arguments:
resource -- a gtk:builder-scope object used when constructing list items
Details:
Accessor of the scope slot of the gtk:builder-list-item-factory class. Gets the scope used when constructing list items.
See also:
2025-4-11
Function gtk:builder-list-item-factory-new-from-bytes (scope bytes)
Arguments:
scope -- a gtk:builder-scope object to use when instantiating
bytes -- a g:bytes instance containing the UI file to instantiate
Returns:
Details:
Creates a new builder list item factory that instantiates widgets using bytes as the data to pass to the gtk:builder object.
See also:
2025-3-16
Function gtk:builder-list-item-factory-new-from-resource (scope path)
Arguments:
scope -- a gtk:builder-scope object to use when instantiating
path -- a string for a valid path to a resource that contains the data
Returns:
Details:
Creates a new builder list item factory that instantiates widgets using data read from the given resource path to pass to the gtk:builder object.
See also:
2025-3-16

GtkScrollInfo

GBoxed gtk:scroll-info
Declaration:
(glib:define-gboxed-opaque scroll-info "GtkScrollInfo"
  :export t
  :type-initializer "gtk_scroll_info_get_type"
  :alloc (%scroll-info-new))  
Returned by:
Details:
The gtk:scroll-info structure can be used to provide more accurate data on how a scroll operation should be performed. Scrolling functions usually allow passing a nil value for the scroll info which will cause the default values to be used and just scroll the item into view.

Since 4.12
See also:
2025-4-7
Function gtk:scroll-info-new ()
Returns:
The new gtk:scroll-info instance.
Details:
Creates a new scroll info for scrolling an item into view.

Since 4.12
See also:
2025-4-7
Function gtk:scroll-info-enable-horizontal (scrollinfo)
Syntax:
(gtk:scroll-info-enable-horizontal scrollinfo) => enable
(setf (gtk:scroll-info-enable-horizontal scrollinfo) enable)
Arguments:
scrollinfo -- a gtk:scroll-info instance
enable -- a boolean whether scrolling in the horizontal direction should happen
Details:
Turns horizontal scrolling on or off.

Since 4.12
See also:
2025-4-7
Function gtk:scroll-info-enable-vertical (scrollinfo)
Syntax:
(gtk:scroll-info-enable-vertical scrollinfo) => enable
(setf (gtk:scroll-info-enable-vertical scrollinfo) enable)
Arguments:
scrollinfo -- a gtk:scroll-info instance
enable -- a boolean whether scrolling in the vertical direction should happen
Details:
Turns vertical scrolling on or off.

Since 4.12
See also:
2025-4-7

GtkListHeader

Class gtk:list-header
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The widget used for display.
end
The end property of type guint (Read)
The first position no longer part of the section.
Default value: gtk:+invalid-list-position+
item
The item property of type g:object (Read)
The item at the start of the section.
n-items
The n-items property of type guint (Read)
The number of items in the section.
start
The start property of type guint (Read)
The first position of items in the section.
Default value: gtk:+invalid-list-position+
Slot Access Functions:
Details:
The gtk:list-header object is used by list widgets to represent the headers they display.

The gtk:list-header objects are managed just like gtk:list-item objects through their factory, but provide a different set of properties suitable for managing the header instead of individual items.

Since 4.12
See also:
2025-4-7
Accessor gtk:list-header-child (object)
Syntax:
(gtk:list-header-child object) => child
(setf (gtk:list-header-child object) child)
Arguments:
object -- a gtk:list-header object
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:list-header class. The gtk:list-header-child function gets the child widget previously set or nil if none was set. The (setf gtk:list-header-child) function sets the child widget to be used for this list item.

This function is typically called by applications when setting up a header so that the widget can be reused when binding it multiple times.

Since 4.12
See also:
2025-4-11
Accessor gtk:list-header-end (object)
Syntax:
(gtk:list-header-end object) => end
Arguments:
object -- a gtk:list-header object
end -- an unsigned integer for the end position of the section
Details:
Accessor of the end slot of the gtk:list-header class. The gtk:list-header-end function gets the end position in the model of the section that object is currently the header for. If object is unbound, the gtk:+invalid-list-position+ value is returned.

Since 4.12
See also:
2025-4-7
Accessor gtk:list-header-item (object)
Syntax:
(gtk:list-header-item object) => item
Arguments:
object -- a gtk:list-header object
item -- a g:object instance for the item displayed
Details:
Accessor of the item slot of the gtk:list-header class. The gtk:list-header-item function gets the model item at the start of the section. This is the item that occupies the list model at the start position.

If object is unbound, this function returns nil.

Since 4.12
See also:
2025-4-7
Accessor gtk:list-header-n-items (object)
Syntax:
(gtk:list-header-n-items object) => n-items
Arguments:
object -- a gtk:list-header object
n-items -- an unsigned integer for the number of items in the section
Details:
Accessor of the n-items slot of the gtk:list-header class. The gtk:list-header-n-items function gets the the number of items in the section. If object is unbound, 0 is returned.

Since 4.12
See also:
2025-4-7
Accessor gtk:list-header-start (object)
Syntax:
(gtk:list-header-start object) => start
Arguments:
object -- a gtk:list-header object
start -- an unsigned integer for the start position of the section
Details:
Accessor of the start slot of the gtk:list-header class. The gtk:list-header-start function gets the start position in the model of the section that object is currently the header for.

If object is unbound, the gtk:+invalid-list-position+ value is returned.

Since 4.12
See also:
2025-4-7

GtkListView

GEnum gtk:list-tab-behavior
Declaration:
(gobject:define-genum "GtkListTabBehavior" list-tab-behavior
  (:export t
   :type-initializer "gtk_list_tab_behavior_get_type")
  (:all 0)
  (:item 1)
  (:cell 2))  
Values:
:all
Cycle through all focusable items of the list.
:item
Cycle through a single list element, then move focus out of the list. Moving focus between items needs to be done with the arrow keys.
:cell
Cycle only through a single cell, then move focus out of the list. Moving focus between cells needs to be done with the arrow keys. This is only relevant for cell-based widgets like the gtk:column-view widget, otherwise it behaves like :item.
Details:
Used to configure the focus behavior in the :forward and :backward direction, like the Tab key in a gtk:list-view widget.

Since 4.12
See also:
2025-4-8
GFlags gtk:list-scroll-flags
Declaration:
(gobject:define-gflags "GtkListScrollFlags" list-scroll-flags
  (:export t
   :type-initializer "gtk_list_scroll_flags_get_type")
  (:none 0)
  (:focus #.(ash 1 0))
  (:select #.(ash 1 1)))  
Values:
:none
Do not do anything extra.
:focus
Focus the target item.
:select
Select the target item and unselect all other items.
Details:
List of actions to perform when scrolling to items in a list widget.

Since 4.12
See also:
2025-4-8
Class gtk:list-base
Superclasses:
Documented Subclasses:
Direct Slots:
orientation
The orientation property of type gtk:orientation (Read / Write)
The orientation of the list widget.
Default value: :vertical
Slot Access Functions:
Details:
The gtk:list-base class is the abstract base class for GTK list widgets.
See also:
2025-4-8
Accessor gtk:list-base-orientation (object)
Syntax:
(gtk:list-base-orientation object) => orientation
(setf (gtk:list-base-orientation object) orientation)
Arguments:
object -- a gtk:list-base widget
orientation -- a gtk:orientation value
Details:
Accessor of the orientation slot of the gtk:list-base class. The gtk:list-base-orientation function gets the orientation of the list widget. The (setf gtk:list-base-orientation) functions sets the orientation.
See also:
2025-4-11
Class gtk:list-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
enable-rubberband
The enable-rubberband property of type :boolean (Read / Write)
Whether to allow rubberband selection.
Default value: false
factory
The factory property of type gtk:list-item-factory (Read / Write)
The factory for populating list items.
header-factory
The header-factory property of type gtk:list-item-factory (Read / Write)
The factory for creating header widgets. Since 4.12
model
The model property of type gtk:selection-model (Read / Write)
The model for the items displayed.
show-separators
The show-separators property of type :boolean (Read / Write)
Whether to show separators between rows.
Default value: false
single-click-activate
The single-click-activate property of type :boolean (Read / Write)
Whether to activate rows on single click and select them on hover.
Default value: false
tab-behavior
The tab-behavior property of type gtk:list-tab-behavior (Read / Write)
The behavior of the Tab and Shift+Tab keys. Since 4.12
Default value: :all
Returned by:
Slot Access Functions:
Details:
The gtk:list-view widget is a widget to present a view into a large dynamic list of items. The gtk:list-view widget uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally. The show-separators property offers a simple way to display separators between the rows.

The gtk:list-view widget allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on rubberband selection, using the enable-rubberband property.

If you need multiple columns with headers, see the gtk:column-view widget.

To learn more about the list widget framework, see the List Widget Overview section.
Examples:
This is a complete example of how to use the gtk:list-view widget. The example is included in the GTK 4 demo, which comes with the cl-cffi-gtk4 library.
(defun activate-cb (listview position)
  (let* ((model (gtk:list-view-model listview))
         (appinfo (g:list-model-item model position))
         (display (gtk:widget-display listview))
         (context (gdk:display-app-launch-context display)))
    (unless (g:app-info-launch appinfo nil context)
      (let* ((message (format nil "Could not launch ~a"
                                  (g:app-info-display-name appinfo)))
             (dialog (make-instance 'gtk:alert-dialog
                                    :message message)))
          (gtk:alert-dialog-show dialog (gtk:widget-root listview))))))

(defun create-application-list () (let ((store (g:list-store-new "GAppInfo")) (apps (g:app-info-all))) (dolist (app apps) (g:list-store-append store app)) store))

(defun do-list-view-applauncher (&optional (application nil)) (let* ((factory (gtk:signal-list-item-factory-new)) (model (create-application-list)) (listview nil) (scrolled (make-instance 'gtk:scrolled-window :margin-start 12 :margin-top 12)) (window (make-instance 'gtk:window :title "Application launcher" :application application :child scrolled :default-width 640 :default-height 320 :margin-start 24 :margin-top 6 :margin-bottom 6))) (g:signal-connect factory "setup" (lambda (factory item) (declare (ignore factory)) (let* ((box (gtk:box-new :horizontal 12)) (image (make-instance 'gtk:image :icon-size :large))) (gtk:box-append box image) (gtk:box-append box (gtk:label-new "")) (setf (gtk:list-item-child item) box)))) (g:signal-connect factory "bind" (lambda (factory item) (declare (ignore factory)) (let* ((image (gtk:widget-first-child (gtk:list-item-child item))) (label (gtk:widget-next-sibling image)) (appinfo (gtk:list-item-item item))) (gtk:image-set-from-gicon image (g:app-info-icon appinfo)) (setf (gtk:label-label label) (g:app-info-display-name appinfo))))) (setf listview (gtk:list-view-new (gtk:single-selection-new model) factory)) (g:signal-connect listview "activate" #'activate-cb) (setf (gtk:scrolled-window-child scrolled) listview) (gtk:window-present window)))
Actions:
The gtk:list-view implementation defines a set of built-in actions:
list.activate-item
Activates the item at given position by emitting the GtkListView::activate signal.
CSS nodes:
listview[.separators][.rich-list][.navigation-sidebar][.data-table]
├── row[.activatable]
│
├── row[.activatable]
│
┊
╰── [rubberband]    
The gtk:list-view implementation uses a single CSS node named listview. It may carry the .separators style class, when the show-separators property is set. Each child widget uses a single CSS node named row. For rubberband selection, a node with name rubberband is used. The main listview node may also carry .rich-list, .navigation-sidebar or .data-table style classes to select the style of list presentation.
Accessibility:
The gtk:list-view implementation uses the :list role, and the list items use the :list-item role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (listview position)    :run-last      
listview
The gtk:list-view widget.
position
The unsigned integer with the position of the item to activate.
The signal is emitted when a row has been activated by the user, usually via activating the GtkListView::list.activate-item action. This allows for a convenient way to handle activation in a list view. See the gtk:list-item-activatable function for details on how to use this signal.
See also:
2025-4-8
Accessor gtk:list-view-enable-rubberband (object)
Syntax:
(gtk:list-view-enable-rubberband object) => setting
(setf (gtk:list-view-enable-rubberband object) setting)
Arguments:
object -- a gtk:list-view object
setting -- true if rubberband selection is enabled
Details:
Accessor of the enable-rubberband slot of the gtk:list-view class. The gtk:list-view-enable-rubberband function returns whether rows can be selected by dragging with the mouse. The (setf gtk:list-view-enable-rubberband) function sets the property.
See also:
2025-4-8
Accessor gtk:list-view-factory (object)
Syntax:
(gtk:list-view-factory object) => factory
(setf (gtk:list-view-factory object) factory)
Arguments:
object -- a gtk:list-view object
factory -- a gtk:list-item-factory object to use, or nil for none
Details:
Accessor of the factory slot of the gtk:list-view class. The gtk:list-view-factory function gets the factory that is currently used to populate list items. The (setf gtk:list-view-factory) function sets the factory.
See also:
2025-4-8
Accessor gtk:list-view-header-factory (object)
Syntax:
(gtk:list-view-header-factory object) => factory
(setf (gtk:list-view-header-factory object) factory)
Arguments:
object -- a gtk:list-view object
factory -- a gtk:list-item-factory object to use
Details:
Accessor of the header-factory slot of the gtk:list-view class. The gtk:list-view-header-factory function gets the factory to use for populating the gtk:list-header objects used in section headers. The (setf gtk:list-view-header-factory) function sets the factory. If this factory is set to nil, the list will not show section headers.

Since 4.12
See also:
2025-4-8
Accessor gtk:list-view-model (object)
Syntax:
(gtk:list-view-model object) => model
(setf (gtk:list-view-model object) model)
Arguments:
object -- a gtk:list-view object
model -- a gtk:selection-model object to use
Details:
Accessor of the model slot of the gtk:list-view class. The gtk:list-view-model function gets the model that is currently used to read the items displayed. The (setf gtk:list-view-model) function sets the model to use. This must be a gtk:selection-model object.
See also:
2025-4-8
Accessor gtk:list-view-show-separators (object)
Syntax:
(gtk:list-view-show-separators object) => setting
(setf (gtk:list-view-show-separators object) setting)
Arguments:
object -- a gtk:list-view object
setting -- true if the list box shows separators
Details:
Accessor of the show-separators slot of the gtk:list-view class. The gtk:list-view-show-separators function returns whether the list box should show separators between rows. The (setf gtk:list-view-show-separators) function sets the property.
See also:
2025-4-8
Accessor gtk:list-view-single-click-activate (object)
Syntax:
(gtk:list-view-single-click-activate object) => setting
(setf (gtk:list-view-single-click-activate object) setting)
Arguments:
object -- a gtk:list-view object
setting -- true if rows are activated on single click
Details:
Accessor of the single-click-activate slot of the gtk:list-view class. The gtk:list-view-single-click-activate function returns whether rows will be activated on single click and selected on hover. The (setf gtk:list-view-single-click-activate) function sets the property.
See also:
2025-4-8
Accessor gtk:list-view-tab-behavior (object)
Syntax:
(gtk:list-view-tab-behavior object) => setting
(setf (gtk:list-view-tab-behavior object) setting)
Arguments:
object -- a gtk:list-view object
setting -- a gtk:list-tab-behavior value
Details:
Accessor of the tab-behavior slot of the gtk:list-view class. The gtk:list-view-tab-behavior function gets the behavior set for the Tab and Shift+Tab keys. The (setf gtk:list-view-tab-behavior) function sets the behavior.

Since 4.12
See also:
2025-4-8
Function gtk:list-view-new (&optional model factory)
Arguments:
model -- an optional gtk:selection-model object to use, or the default nil value
factory -- an optional gtk:list-item-factory object to populate items with or the default nil value
Returns:
The new gtk:list-view widget using the given model and factory.
Details:
Creates a new list view that uses the given factory for mapping items to widgets.
See also:
2025-4-11
Function gtk:list-view-scroll-to (listview pos flags &optional scroll)
Arguments:
listview -- a gtk:list-view widget
pos -- an unsigned integer for the position of the item
flags -- a gtk:list-scroll-flags value for the actions to perform
scroll -- an optional gtk:scroll-info instance for the details of how to perform the scroll operation or the default nil value to scroll into view
Details:
Scrolls to the item at the given position and performs the actions specified in flags. This function works no matter if the list view is shown or focused. If it is not, then the changes will take effect once that happens.

Since 4.12
See also:
#2025-4-8

GtkGridView

Class gtk:grid-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
enable-rubberband
The enable-rubberband property of type :boolean (Read / Write)
Whether to allow rubberband selection.
Default value: false
factory
The factory property of type gtk:list-item-factory (Read / Write)
The factory for populating list items.
max-columns
The max-columns property of type :uint (Read / Write)
The maximum number of columns per row. If this number is smaller than the min-columns property, that value is used instead.
Allowed values: >= 1
Default value: 7
min-columns
The min-columns property of type :uint (Read / Write)
The minimum number of columns per row.
Allowed values: >= 1
Default value: 1
model
The model property of type gtk:selection-model (Read / Write)
The model for the items displayed.
single-click-activate
The single-click-activate property of type :boolean (Read / Write)
Whether to activate rows on single click and select them on hover.
Default value: false
tab-behavior
The tab-beavior property of type gtk:list-tab-behavior (Read / Write)
The behavior of the Tab and Shift+Tab keys.
Default value: :all
Returned by:
Slot Access Functions:
Details:
The gtk:grid-view widget is a widget to present a view into a large dynamic grid of items. The gtk:grid-view widget uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view determines if the grid reflows vertically or horizontally.

The gtk:grid-view widget allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on rubberband selection, using the enable-rubberband property.

To learn more about the list widget framework, see the list widget overview.
Actions:
The gtk:grid-view implementation defines a set of built-in actions:
list.activate-item
Activates the item at given position by emitting the GtkListView::activate signal.
CSS nodes:
gridview
├── child
│
├── child
│
┊
╰── [rubberband]    
The gtk:grid-view implementation uses a single CSS node with name gridview. Each child uses a single CSS node with name child. If the activatable property is set, the corresponding row will have the .activatable style class. For rubberband selection, a subnode with name rubberband is used.
Accessibility:
The gtk:grid-view implementation uses the :grid role, and the items use the :grid-cell role from the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (gridview position)    :run-last      
gridview
The gtk:grid-view widget.
position
The unsigned integer with the position of the item to activate.
The signal is emitted when a cell has been activated by the user. This allows for a convenient way to handle activation in a grid view. See the activatable property for details on how to use this signal.
See also:
2025-4-11
Accessor gtk:grid-view-enable-rubberband (object)
Syntax:
(gtk:grid-view-enable-rubberband object) => setting
(setf (gtk:grid-view-enable-rubberband object) setting)
Arguments:
object -- a gtk:grid-view object
setting -- true if rubberband selection is enabled
Details:
Accessor of the enable-rubberband slot of the gtk:grid-view class. The gtk:grid-view-enable-rubberband function returns whether selections can be selected by dragging with the mouse. The (setf gtk:grid-view-enable-rubberband) function sets the property.
See also:
2025-4-11
Accessor gtk:grid-view-factory (object)
Syntax:
(gtk:grid-view-factory object) => factory
(setf (gtk:grid-view-factory object) factory)
Arguments:
object -- a gtk:grid-view object
factory -- a gtk:list-item-factory object to use, or nil for none
Details:
Accessor of the factory slot of the gtk:grid-view class. The gtk:grid-view-factory function gets the factory that is currently used to populate list items. The (setf gtk:grid-view-factory) function sets the factory.
See also:
2025-4-11
Accessor gtk:grid-view-max-columns (object)
Syntax:
(gtk:grid-view-max-colums object) => max
(setf (gtk:grid-view-max-columns object) max)
Arguments:
object -- a gtk:grid-view object
max -- an unsigned integer for the maximum of columns
Details:
Accessor of the max-columns slot of the gtk:grid-view class. The gtk:grid-view-max-columns function gets the maximum number of columns that the grid will use. The (setf gtk:grid-view-max-columns) function sets the maximum number. This number must be at least 1. If the max-columns property is smaller than the minimum set via the gtk:grid-view-min-columns function, that value is used instead.
See also:
2025-4-11
Accessor gtk:grid-view-min-columns (object)
Syntax:
(gtk:grid-view-max-colums object) => min
(setf (gtk:grid-view-min-columns object) min)
Arguments:
object -- a gtk:grid-view object
min -- an unsigned integer for the minimum of columns
Details:
Accessor of the min-columns slot of the gtk:grid-view class. The gtk:grid-view-min-columns function gets the minimum number of columns that the grid will use. The (setf gtk:grid-view-min-columns) function sets the minimum number. This number must be at least 1. If the min-columns property is smaller than the minimum set via the gtk:grid-view-max-columns function, that value is ignored.
See also:
2025-4-11
Accessor gtk:grid-view-model (object)
Syntax:
(gtk:grid-view-model object) => model
(setf (gtk:grid-view-model object) model)
Arguments:
object -- a gtk:grid-view object
model -- a gtk:selection-model object to use
Details:
Accessor of the model slot of the gtk:grid-view class. The gtk:grid-view-model function gets the model that is currently used to read the items displayed. The (setf gtk:grid-view-model) function sets the model to use. This must be a gtk:selection-model object.
See also:
2025-4-11
Accessor gtk:grid-view-single-click-activate (object)
Syntax:
(gtk:grid-view-single-click-activate object) => setting
(setf (gtk:grid-view-single-click-activate object) setting)
Arguments:
object -- a gtk:grid-view object
setting -- true if rows are activated on single click
Details:
Accessor of the single-click-activate slot of the gtk:grid-view class. The gtk:grid-view-single-click-activate function returns whether rows will be activated on single click and selected on hover. The (setf gtk:grid-view-single-click-activate) function sets the property.
See also:
2025-4-11
Accessor gtk:grid-view-tab-behavior (object)
Syntax:
(gtk:grid-view-tab-behavior object) => setting
(setf (gtk:grid-view-tab-behavior object) setting)
Arguments:
object -- a gtk:grid-view object
setting -- a gtk:list-tab-behavior value
Details:
Accessor of the tab-behavior slot of the gtk:grid-view class. The gtk:grid-view-tab-behavior function gets the behavior of the Tab and Shift+Tab keys. The (setf gtk:grid-view-tab-behavior) function sets the tab behavior.
See also:
2025-4-11
Function gtk:grid-view-new (&optional model factory)
Arguments:
model -- an optional gtk:selection-model object to use, or the nil default value
factory -- an optional gtk:list-item-factory object to populate items with or the default nil value
Returns:
The new gtk:grid-view widget using the given model and factory.
Details:
Creates a new grid view that uses the given factory for mapping items to widgets.
See also:
2025-4-11
Function gtk:grid-view-scroll-to (gridview pos flags &optional scroll)
Arguments:
gridview -- a gtk:grid-view widget
pos -- an unsigned integer for the position of the item
flags -- a gtk:list-scroll-flags value for the actions to perform
scroll -- an optional gtk:scroll-info instance for the details of how to perform the scroll operation or the default nil value to scroll into view
Details:
Scrolls to the item at the given position and performs the actions specified in flags. This function works no matter if the grid view is shown or focused. If it is not, then the changes will take effect once that happens.

Since 4.12
See also:
#2025-4-11

GtkColumnView

Class gtk:column-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
columns
The columns property of type g:list-model (Read)
The list of columns.
enable-rubberband
The enable-rubberband property of type :boolean (Read / Write)
Whether to allow rubberband selection.
Default value: false
header-factory
The header-factory property of type gtk:list-item-factory (Read / Write)
The factory for creating header widgets. Since 4.12
model
The model property of type gtk:selection-model (Read / Write)
The model for the items displayed.
reorderable
The reorderable property of type :boolean (Read / Write)
Whether columns are reorderable.
Default value: true
row-factory
The row-factory property of type gtk:list-item-factory (Read / Write)
The factory used for configuring rows. Since 4.12
show-column-separators
The show-column-separators property of type :boolean (Read / Write)
Whether to show separators between columns.
Default value: false
show-row-separators
The show-row-separators property of type :boolean (Read / Write)
Whether to show separators between rows.
Default value: false
single-click-activate
The single-click-activate property of type :boolean (Read / Write)
Whether to activate rows on single click and select them on hover.
Default value: false
sorter
The sorter property of type gtk:sorter (Read)
The sorter with the sorting choices of the user.
tab-behavior
The tab-behavior property of type gtk:list-tab-behavior (Read / Write)
The behavior of the Tab and Shift+Tab keys.
Default value: :all
Returned by:
Slot Access Functions:
Details:
The gtk:column-view widget is a widget to present a view into a large dynamic list of items using multiple columns with headers. The gtk:column-view widget uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for this item. The show-row-separators and show-column-separators properties offer a simple way to display separators between the rows or columns.

The gtk:column-view widget allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on rubberband selection, using the enable-rubberband property.

The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the gtk:sorter object returned by the gtk:column-view-sorter function must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling (setf gtk:column-view-column-sorter) function. The initial sort order can be set with the gtk:column-view-sort-by-column function.

The column view also supports interactive resizing and reordering of columns, via Drag-and-Drop of the column headers. This can be enabled or disabled with the reorderable and resizable properties.

To learn more about the list widget framework, see the list widget overview.
CSS nodes:
The gtk:column-view implementation uses a single CSS node named columnview. It may carry the .column-separators style class, when show-column-separators property is set. Header widgets appear below a node with name header. The rows are contained in a gtk:list-view widget, so there is a listview node with the same structure as for a standalone gtk:list-view widget. If the show-row-separators property is set, it will be passed on to the list view, causing its CSS node to carry the .separators style class. For rubberband selection, a node with name rubberband is used. The main columnview node may also carry .rich-list, .navigation-sidebar or .data-table style classes to select the style of list presentation.
Accessibility:
The gtk:column-view implementation uses the :tree-grid role of the gtk:accessible-role enumeration, header title widgets are using the :column-header role. The row widgets are using the :row role, and individual cells are using the :grid-cell role.
Signal Details:
The "activate" signal
lambda (columnview position)    :run-last      
columnview
The gtk:column-view widget.
position
The unsigned integer with the position of the item to activate.
The signal is emitted when a row has been activated by the user. This allows for a convenient way to handle activation in a columnview. See the gtk:list-item-activatable function for details on how to use this signal.
See also:
2025-4-13
Accessor gtk:column-view-columns (object)
Syntax:
(gtk:column-view-columns object) => columns
Arguments:
object -- a gtk:column-view object
columns -- a g:list-model object for the list managing the columns
Details:
Accessor of the columns slot of the gtk:column-view class. The gtk:column-view-columns function gets the list of columns in this column view. This list is constant over the lifetime of object and can be used to monitor changes to the columns of object by connecting to the "items-changed" signal.
See also:
2025-4-13
Accessor gtk:column-view-enable-rubberband (object)
Syntax:
(gtk:column-view-enable-rubberband object) => setting
(setf (gtk:column-view-enable-rubberband object) setting)
Arguments:
object -- a gtk:column-view object
setting -- true if rubberband selection is enabled
Details:
Accessor of the enable-rubberband slot of the gtk:column-view class. The gtk:column-view-enable-rubberband function returns whether rows can be selected by dragging with the mouse. The (setf gtk:column-view-enable-rubberband) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-header-factory (object)
Syntax:
(gtk:column-view-header-factory object) => factory
(setf (gtk:column-view-header-factory object) factory)
Arguments:
object -- a gtk:column-view object
factory -- a gtk:list-item-factory object to use
Details:
Accessor of the header-factory slot of the gtk:column-view class. The gtk:column-view-header-factory function gets the factory to use for populating the gtk:list-header objects used in section headers. The (setf gtk:column-view-header-factory) function sets the factory. If this factory is set to nil, the list will not show section headers.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-model (object)
Syntax:
(gtk:column-view-model object) => model
(setf (gtk:column-view-model object) model)
Arguments:
object -- a gtk:column-view object
model -- a gtk:selection-model object to use, or nil for none
Details:
Accessor of the model slot of the gtk:column-view class. The gtk:column-view-model function gets the model that is currently used to read the items displayed. The (setf gtk:column-view-model) function sets the model to use. This must be a gtk:selection-model object.
See also:
2025-4-13
Accessor gtk:column-view-reorderable (object)
Syntax:
(gtk:column-view-reorderable object) => reorderable
(setf (gtk:column-view-reorderable object) reorderable)
Arguments:
object -- a gtk:column-view object
reorderable -- true if columns are reorderable
Details:
Accessor of the reorderable slot of the gtk:column-view class. The gtk:column-view-reorderable function returns whether columns are reorderable. The (setf gtk:column-view-reorderable) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-row-factory (object)
Syntax:
(gtk:column-view-row-factory object) => factory
(setf (gtk:column-view-row-factory object) factory)
Arguments:
object -- a gtk:column-view object
factory -- a gtk:list-item-factory object to use
Details:
Accessor of the row-factory slot of the gtk:column-view class. The gtk:column-view-row-factory function gets the factory that is used for configuring rows. The (setf gtk:column-view-row-factory) function sets the factory. The factory must be for configuring gtk:column-view-row objects.

If this factory is not set - which is the default - then the defaults will be used. This factory is not used to set the widgets displayed in the individual cells. For that see the gtk:column-view-column-factory function and the gtk:column-view-cell object.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-show-column-separators (object)
Syntax:
(gtk:column-view-show-column-separators object) => setting
(setf (gtk:column-view-show-column-separators object) setting)
Arguments:
object -- a gtk:column-view object
setting -- true to show column separators
Details:
Accessor of the show-column-separators slot of the gtk:column-view class. The gtk:column-view-show-column-separators function returns whether the list should show separators between columns. The (setf gtk:column-view-show-column-separators) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-show-row-separators (object)
Syntax:
(gtk:column-view-show-row-separators object) => setting
(setf (gtk:column-view-show-row-separators object) setting)
Arguments:
object -- a gtk:column-view object
setting -- true to show column separators
Details:
Accessor of the show-row-separators slot of the gtk:column-view class. The gtk:column-view-show-row-separators function returns whether the list should show separators between rows. The (setf gtk:column-view-show-row-separators) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-single-click-activate (object)
Syntax:
(gtk:column-view-single-click-activate object) => setting
(setf (gtk:column-view-single-click-activate object) setting)
Arguments:
object -- a gtk:column-view object
setting -- true if rows are activated on single click
Details:
Accessor of the single-click-activate slot of the gtk:column-view class. The gtk:column-view-single-click-activate function returns whether rows will be activated on single click and selected on hover. The (setf gtk:column-view-single-click-activate) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-sorter (object)
Syntax:
(gtk:column-view-sorter object) => sorter
Arguments:
object -- a gtk:column-view object
sorter -- a gtk:sorter object
Details:
Accessor of the sorter slot of the gtk:column-view class. The gtk:column-view-sorter function returns a special sorter that reflects the users sorting choices in the column view. To allow users to customizable sorting by clicking on column headers, this sorter needs to be set on the sort model underneath the model that is displayed by the view. See the gtk:column-view-column-sorter function for setting up per-column sorting.
Examples:
Here is an example:
gtk_column_view_column_set_sorter (column, sorter);
gtk_column_view_append_column (view, column);
sorter = g_object_ref (gtk_column_view_get_sorter (view)));
model = gtk_sort_list_model_new (store, sorter);
selection = gtk_no_selection_new (model);
gtk_column_view_set_model (view, selection);    
See also:
2025-4-13
Accessor gtk:column-view-tab-behavior (object)
Syntax:
(gtk:column-view-tab-behavior object) => setting
(setf (gtk:column-view-tab-behavior object) setting)
Arguments:
object -- a gtk:column-view object
setting -- a gtk:list-tab-behavior value
Details:
Accessor of the tab-behavior slot of the gtk:column-view class. The gtk:column-view-tab-behavior function gets the behavior of the Tab and Shift+Tab keys. The (setf gtk:column-view-tab-behavior) function sets the tab behavior.
See also:
2025-4-13
Function gtk:column-view-new (&optional model)
Arguments:
model -- a gtk:selection-model object to use, or the default nil value
Returns:
The new gtk:column-view widget.
Details:
Creates a new gtk:column-view widget. You most likely want to call the gtk:column-view-append-column function to add columns next.
See also:
2025-4-13
Function gtk:column-view-append-column (columnview column)
Arguments:
columnview -- a gtk:column-view widget
column -- a gtk:column-view-column object that has not been added to column view yet
Details:
Appends the column to the end of the columns in columnview.
See also:
2025-4-13
Function gtk:column-view-insert-column (columnview pos column)
Arguments:
columnview -- a gtk:column-view widget
pos -- an unsigned integer for the position to insert column at
column -- a gtk:column-view-column object to insert
Details:
Inserts a column at the given pos in the columns of columview. If column is already a column of columnview, it will be repositioned.
See also:
2025-4-13
Function gtk:column-view-remove-column (columnview column)
Arguments:
columnview -- a gtk:column-view widget
column -- a gtk:column-view-column object to remove
Details:
Removes the column from the list of columns of columnview.
See also:
2025-4-13
Function gtk:column-view-sort-by-column (columnview column direction)
Arguments:
columnview -- a gtk:column-view widget
column -- a gtk:column-view-column object to sort by, or nil
direction -- a gtk:sort-type value for the direction to sort in
Details:
Sets the sorting of the column view. This function should be used to set up the initial sorting. At runtime, users can change the sorting of a column view by clicking on the list headers.

This call only has an effect if the sorter returned by the gtk:column-view-sorter function is set on a sort model, and the (setf gtk:column-view-column-sorter) function has been called on column to associate a sorter with the column.

If column is nil, the column view will be unsorted.
See also:
#2025-4-13

GtkColumnViewColumn

Class gtk:column-view-column
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
column-view
The column-view property of type gtk:column-view (Read)
The column view this column is a part of.
expand
The expand property of type :boolean (Read)
Whether the column gets share of extra width allocated to the view.
Default value: false
factory
The factory property of type gtk:list-item-factory (Read / Write)
The factory for populating list items.
fixed-width
The fixed-width property of type :int (Read / Write)
If not -1, this is the width that the column is allocated, regardless of the size of its content.
Allowed values: >= -1
Default value: -1
header-menu
The header-menu property of type g:menu-model (Read / Write)
The menu model used to create the context menu for the column header.
id
The id property of type :string (Read / Write)
The ID for the column. GTK is not currently using the ID for anything, but it can be used by applications when saving column view configurations. It is up to applications to ensure uniqueness of IDs.
Default value: nil
resizable
The resizable property of type :boolean (Read / Write)
Whether this column is resizable.
Default value: false
sorter
The sorter property of type gtk:sorter (Read / Write)
The sorter for sorting items according to this column.
title
The title property of type :string (Read / Write)
The title displayed in the header.
Default value: nil
visible
The visible property of type :boolean (Read / Write)
Whether this column is visible.
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:column-view-column widget represents the columns being added to the gtk:column-view widget. Columns have a title, and can optionally have a header menu set with the gtk:column-view-column-header-menu function.

A sorter can be associated with a column using the gtk:column-view-column-sorter function, to let users influence sorting by clicking on the column header.
See also:
2025-4-13
Accessor gtk:column-view-column-column-view (object)
Syntax:
(gtk:column-view-column-column-view object) => columnview
Arguments:
object -- a gtk:column-view-column object
columnview -- a gtk:column-view widget displaying object
Details:
Accessor of the column-view slot of the gtk:column-view-column class. The gtk:column-view-column-column-view function gets the column view that is currently displaying this column. If object has not been added to a column view yet, nil is returned.
See also:
2025-4-13
Accessor gtk:column-view-column-expand (object)
Syntax:
(gtk:column-view-column-expand object) => expand
(setf (gtk:column-view-column-expand object) expand)
Arguments:
object -- a gtk:column-view-column object
expand -- true if this column expands
Details:
Accessor of the expand slot of the gtk:column-view-column class. The gtk:column-view-column-expand function returns whether this column should expand. The (setf gtk:column-view-column-expand) function sets the column to take available extra space. The extra space is shared equally amongst all columns that have the expand set to true.
See also:
2025-4-13
Accessor gtk:column-view-column-factory (object)
Syntax:
(gtk:column-view-column-factory object) => factory
(setf (gtk:column-view-column-factory object) factory)
Arguments:
object -- a gtk:column-view-column object
factory -- a gtk:list-item-factory object to use, or nil for none
Details:
Accessor of the factory slot of the gtk:column-view-column class. The gtk:column-view-column-factory function gets the factory that is currently used to populate list items. The (setf gtk:column-view-column-factory) function sets the factory.
See also:
2025-4-13
Accessor gtk:column-view-column-fixed-width (object)
Syntax:
(gtk:column-view-column-fixed-width object) => width
(setf (gtk:column-view-column-fixed-width object) width)
Arguments:
object -- a gtk:column-view-column object
width -- an integer for the fixed width of the column
Details:
Accessor of the fixed-width slot of the gtk:column-view-column class. The gtk:column-view-column-fixed-width function gets the fixed width of the column. The (setf gtk:column-view-column-fixed-width) function sets the fixed width. If width is not -1, sets the fixed width of object, otherwise unsets it.

Setting a fixed width overrides the automatically calculated width. Interactive resizing also sets the fixed-width property.
See also:
2025-4-13
Accessor gtk:column-view-column-header-menu (object)
Syntax:
(gtk:column-view-column-header-menu object) => menu
(setf (gtk:column-view-column-header-menu object) menu)
Arguments:
object -- a gtk:column-view-column object
menu -- a g:menu-model object, or nil
Details:
Accessor of the header-menu slot of the gtk:column-view-column class. The gtk:column-view-column-header-menu function gets the menu model that is used to create the context menu for the column header. The (setf gtk:column-view-column-header-menu) function sets the menu model.
See also:
2025-4-13
Accessor gtk:column-view-column-id (object)
Syntax:
(gtk:column-view-column-id object) => id
(setf (gtk:column-view-column-id object) id)
Arguments:
object -- a gtk:column-view-column object
id -- a string for the ID to use for this column
Details:
Accessor of the id slot of the gtk:column-view-column class. The gtk:column-view-column-id function returns the ID. The (setf gtk:column-view-column-id) function sets the ID of this column. GTK makes no use of this, but applications can use it when storing column view configuration. It is up to callers to ensure uniqueness of IDs.

Since 4.10
See also:
2025-4-13
Accessor gtk:column-view-column-resizable (object)
Syntax:
(gtk:column-view-column-resizable object) => resizable
(setf (gtk:column-view-column-resizable object) resizable)
Arguments:
object -- a gtk:column-view-column object
resizable -- true if this column is resizable
Details:
Accessor of the resizable slot of the gtk:column-view-column class. The gtk:column-view-column-resizable function returns whether this column is resizable by dragging. The (setf gtk:column-view-column-resizable) function sets the property.
See also:
2025-4-13
Accessor gtk:column-view-column-sorter (object)
Syntax:
(gtk:column-view-column-sorter object) => sorter
(setf (gtk:column-view-column-sorter object) sorter)
Arguments:
object -- a gtk:column-view-column object
sorter -- a gtk:sorter object
Details:
Accessor of the sorter slot of the gtk:column-view-column class. The gtk:column-view-column-sorter function returns the sorter that is associated with the column. The (setf gtk:column-view-column-sorter) function associates a sorter with the column. If sorter is nil, the column will not let users change the sorting by clicking on its header. This sorter can be made active by clicking on the column header, or by calling the gtk:column-view-sort-by-column function.

See the gtk:column-view-sorter function for the necessary steps for setting up customizable sorting for the column view.
See also:
2025-4-13
Accessor gtk:column-view-column-title (object)
Syntax:
(gtk:column-view-column-title object) => title
(setf (gtk:column-view-column-title object) title)
Arguments:
object -- a gtk:column-view-column object
title -- a string for the title of the column
Details:
Accessor of the title slot of the gtk:column-view-column class. The gtk:column-view-column-title function returns the title of this column. The (setf gtk:column-view-column-sorter) function sets the title. The title is displayed in the header of a gtk:column-view widget for this column and is therefore user-facing text that should be translated.
See also:
2025-4-13
Accessor gtk:column-view-column-visible (object)
Syntax:
(gtk:column-view-column-visible object) => visible
(setf (gtk:column-view-column-visible object) visible)
Arguments:
object -- a gtk:column-view-column object
visible -- true if this column is visible
Details:
Accessor of the visible slot of the gtk:column-view-column class. The gtk:column-view-column-visible function returns whether this column is visible in views. The (setf gtk:column-view-column-visible) function sets the property.
See also:
2025-4-13
Function gtk:column-view-column-new (&optional title factory)
Arguments:
title -- an optional string for the title to use for this column, or the default nil value
factory -- an optional gtk:list-item-factory object to populate items with, or the default nil value
Returns:
The new gtk:column-view-column object using the given factory.
Details:
Creates a new column that uses the given factory for mapping items to widgets. You most likely want to call the gtk:column-view-append-column function next.
See also:
2025-4-13

GtkColumnViewCell

Class gtk:column-view-cell
Superclasses:
gtk:list-item, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The widget used for display.
focusable
The focusable property of type :boolean (Read / Write)
Whether the item can be focused with the keyboard.
item
The item property of type g:object (Read)
The displayed item.
position
The position property of type :uint (Read)
The position of the item.
Default value: gtk:+invalid-list-position+
selected
The selected property of type :boolean (Read)
Whether the item is currently selected.
Default value: false
Slot Access Functions:
Details:
The gtk:column-view-cell object is used by the gtk:column-view-column object to represent items in a cell in the gtk:column-view widget.

The gtk:column-view-cell objects are managed by the gtk:column-view widget with its factory and cannot be created by applications, but they need to be populated by application code. This is done by calling the gtk:column-view-cell-child function.

The gtk:column-view-cell objects exist in 2 stages:
  1. The unbound stage where the listitem is not currently connected to an item in the list. In that case, the item property is set to nil.
  2. The bound stage where the listitem references an item from the list. The item property is not nil.
Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-cell-child (object)
Syntax:
(gtk:column-view-cell-child object) => child
(setf (gtk:column-view-cell-child object) child)
Arguments:
object -- a gtk:column-view-cell object
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:column-view-cell class. The gtk:column-view-cell-child function gets the child widget previously set or nil if none was set. The (setf gtk:column-view-cell-child) function sets the child widget to be used for this list item.

This function is typically called by applications when setting up a list item so that the widget can be reused when binding it multiple times.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-cell-focusable (object)
Syntax:
(gtk:column-view-cell-focusable object) => focusable
(setf (gtk:column-view-cell-focusable object) focusable)
Arguments:
object -- a gtk:column-view-cell object
focusable -- a boolean whether the item should be focusable
Details:
Accessor of the focusable slot of the gtk:column-view-cell class. The gtk:column-view-cell-focusable function checks if a list item has been set to be focusable. The (setf gtk:column-view-cell-focusable) function sets object to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to the gtk:widget-focusable function.

Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the children of the listitem is focusable. By default, list items are focusable.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-cell-item (object)
Syntax:
(gtk:column-view-cell-item object) => item
Arguments:
object -- a gtk:column-view-cell object
item -- a g:object instance for the item displayed
Details:
Accessor of the item slot of the gtk:column-view-cell class. The gtk:column-view-cell-item function gets the model item that associated with object. If object is unbound, this function returns nil.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-cell-position (object)
Syntax:
(gtk:column-view-cell-position object) => position
Arguments:
object -- a gtk:column-view-cell object
position -- an unsigned integer for the position of the item
Details:
Accessor of the position slot of the gtk:column-view-cell class. The gtk:column-view-cell-position function gets the position in the model that object currently displays. If object is unbound, the gtk:+invalid-list-position+ value is returned.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-cell-selected (object)
Syntax:
(gtk:column-view-cell-selected object) => selected
Arguments:
object -- a gtk:column-view-cell object
selected -- a boolean whether the item is currently selected
Details:
Accessor of the selected slot of the gtk:column-view-cell class. The gtk:column-view-cell-selected function checks whether the item is displayed as selected. The selected state is maintained by the list widget and its model and cannot be set otherwise.

Since 4.12
See also:
2025-4-13

GtkColumnViewRow

Class gtk:column-view-row
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accessible-description
The accessible-description property of type :string (Read / Write)
The accessible description to set on the row.
Default value: nil
accessible-label
The accessible-label property of type :string (Read / Write)
The accessible label to set on the row.
Default value: nil
activatable
The activatable property of type :boolean (Read / Write)
Whether the row can be activated by the user.
Default value: true
focusable
The focusable property of type :boolean (Read / Write)
Whether the row can be focused with the keyboard.
Default value: true
item
The item property of type g:object (Read)
The item for the row.
position
The position property of type :uint (Read)
The position of the row.
Default value: gtk:+invalid-list-position+
selectable
The selectable property of type :boolean (Read / Write)
Whether the row can be selected by the user.
Default value: true
selected
The selected property of type :boolean (Read)
Whether the item in the row is currently selected.
Default value: false
Slot Access Functions:
Details:
The gtk:column-view-row object is used by the gtk:column-view widget to allow configuring how rows are displayed. It is not used to set the widgets displayed in the individual cells. For that see the gtk:column-view-column-factory function and the gtk:column-view-cell object.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-accessible-description (object)
Syntax:
(gtk:column-view-row-accessible-description object) => description
(setf (gtk:column-view-row-accessible-description object) description)
Arguments:
object -- a gtk:column-view-row object
description -- a string for the accessible description
Details:
Accessor of the accessible-description slot of the gtk:column-view-row class. The gtk:column-view-row-accessible-description function gets the accessible description for the row, which may be used, for example by screen readers. The (setf gtk:column-view-row-accessible-description) function sets the accessible description.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-accessible-label (object)
Syntax:
(gtk:column-view-row-accessible-label object) => label
(setf (gtk:column-view-row-accessible-label object) label)
Arguments:
object -- a gtk:column-view-row object
label -- a string for the accesible label
Details:
Accessor of the accessible-label slot of the gtk:column-view-row class. The gtk:column-view-row-accessible-label function gets the accessible label for the row, which may be used, for example by screen readers. The (setf gtk:column-view-row-accessible-label) function sets the accessible label.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-activatable (object)
Syntax:
(gtk:column-view-row-activatable object) => activatable
(setf (gtk:column-view-row-activatable object) activatable)
Arguments:
object -- a gtk:column-view-row object
activatable -- a boolean whether the row can be activated
Details:
Accessor of the activatable slot of the gtk:column-view-row class. The gtk:column-view-row-activatable function checks if the row has been set to be activatable. The (setf gtk:column-view-row-activatable) function sets object to be activatable.

If a row is activatable, double-clicking on the row, using the Return key or calling the gtk:widget-activate function will activate the row. Activating instructs the containing columnview to emit the "GtkColumnView::activate" signal.

By default, the rows are activatable.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-focusable (object)
Syntax:
(gtk:column-view-row-focusable object) => focusable
(setf (gtk:column-view-row-focusable object) focusable)
Arguments:
object -- a gtk:column-view-row object
focusable -- a boolean whether the row can be focused
Details:
Accessor of the focusable slot of the gtk:column-view-row class. The gtk:column-view-row-focusable function checks if a row item has been set to be focusable. The (setf gtk:column-view-row-focusable) function sets object to be focusable. If a row is focusable, it can be focused using the keyboard. This works similar to the gtk:widget-focusable function.

Note that if rows are not focusable, the contents of cells can still be focused if they are focusable.

By default, rows are focusable.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-item (object)
Syntax:
(gtk:column-view-row-item object) => item
Arguments:
object -- a gtk:column-view-row object
item -- a g:object instance for the item for the row
Details:
Accessor of the item slot of the gtk:column-view-row class. The gtk:column-view-row-item function gets the model item that associated with object. If object is unbound, this function returns nil.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-position (object)
Syntax:
(gtk:column-view-row-position object) => position
Arguments:
object -- a gtk:column-view-row object
position -- an unsigned integer for the position of the row
Details:
Accessor of the position slot of the gtk:column-view-row class. The gtk:column-view-row-position function gets the position in the model that object currently displays. If object is unbound, the gtk:+invalid-list-position+ value is returned.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-selectable (object)
Syntax:
(gtk:column-view-row-selectable object) => selectable
(setf (gtk:column-view-row-selectable object) selectable)
Arguments:
object -- a gtk:column-view-row object
selectable -- a boolean whether the row can be selected
Details:
Accessor of the selectable slot of the gtk:column-view-row class. The gtk:column-view-row-selectable function checks if the row has been set to be selectable. The (setf gtk:column-view-row-selectable) function sets object to be selectable.

If a row is selectable, clicking on the row or using the keyboard will try to select or unselect the row. Whether this succeeds is up to the model to determine, as it is managing the selected state.

Note that this means that making a row non-selectable has no influence on the selected state at all. A non-selectable row may still be selected.

By default, rows are selectable.

Since 4.12
See also:
2025-4-13
Accessor gtk:column-view-row-selected (object)
Syntax:
(gtk:column-view-row-selected object) => selected
Arguments:
object -- a gtk:column-view-row object
selected -- a boolean whether the item in the row is selected
Details:
Accessor of the selected slot of the gtk:column-view-row class. The gtk:column-view-row-selected function checks if the item is selected that this row corresponds to. The selected state is maintained by the list widget and its model and cannot be set otherwise.

Since 4.12
See also:
2025-4-13

GtkColumnViewSorter

Class gtk:column-view-sorter
Superclasses:
gtk:sorter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
primary-sort-column
The primary-sort-column property of type gtk:column-view-column (Read)
The primary sort column is the one that displays the triangle in a column view header.
Default value: 0
primary-sort-order
The primary-sort-order property of type gtk:sort-type (Read)
The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards.
Default value: :ascending
Slot Access Functions:
Details:
The gtk:column-view-sorter class is a sorter implementation that is geared towards the needs of the gtk:column-view widget. The sorter returned by the gtk:column-view-sorter function is a gtk:column-view-sorter object.

In column views, sorting can be configured by associating sorters with columns, and users can invert sort order by clicking on column headers. The gtk:column-view-sorter API is designed to allow saving and restoring this configuration.

If you are only interested in the primary sort column, that is, the column where a sort indicator is shown in the header, then you can just look at the primary-sort-column and primary-sort-order properties.

If you want to store the full sort configuration, including secondary sort columns that are used for tie breaking, then you can use the gtk:column-view-sorter-nth-sort-column function. To get notified about changes, use the "changed" signal.

Since 4.10
Examples:
To restore a saved sort configuration on a gtk:column-view widget, use code like:
sorter = gtk_column_view_get_sorter (view);
for (i = gtk_column_view_sorter_get_n_sort_columns (sorter) - 1; i >= 0; i--)
  {
    column = gtk_column_view_sorter_get_nth_sort_column (sorter, i, &order);
    gtk_column_view_sort_by_column (view, column, order);
  }    
See also:
2025-3-30
Accessor gtk:column-view-sorter-primary-sort-column (object)
Syntax:
(gtk:column-view-sorter-primary-sort-column object) => column
Arguments:
object -- a gtk:column-view-sorter object
column -- a gtk:column-view-column object for the primary sort column
Details:
Accessor of the primary-sort-column slot of the gtk:column-view-sorter class. Returns the primary sort column. The primary sort column is the one that displays the triangle in a column view header.

Since 4.10
See also:
2025-3-30
Accessor gtk:column-view-sorter-primary-sort-order (object)
Syntax:
(gtk:column-view-sorter-primary-sort-order object) => order
Arguments:
object -- a gtk:column-view-sorter object
column -- a gtk:sort-type value for the primary sort order
Details:
Accessor of the primary-sort-order slot of the gtk:column-view-sorter class. Returns the primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards. If there is no primary sort column, then this function returns the :ascending value.

Since 4.10
See also:
2025-3-30
Function gtk:column-view-sorter-n-sort-columns (sorter)
Arguments:
sorter -- a gtk:column-view-sorter object
Returns:
The unsigned integer with the number of sort columns.
Details:
Returns the number of columns by which the sorter sorts. If the sorter of the primary sort column does not determine a total order, then the secondary sorters are consulted to break the ties. Use the "changed" signal to get notified when the number of sort columns changes.

Since 4.10
See also:
2025-3-30
Function gtk:column-view-sorter-nth-sort-column (sorter pos)
Syntax:
(gtk:column-view-sorter-nth-sort-column sorter pos) => column, order
Arguments:
sorter -- a gtk:column-view-sorter object
pos -- an unsigned integer for the position of the sort column to retrieve, 0 for the primary sort column
column -- a gtk:column-view-column object
order -- a gtk:sort-type value for the sort order
Details:
Gets the position‘th sort column and its associated sort order. Use the "changed" signal to get notified when sort columns change.

Since 4.10
See also:
2025-3-30

GtkDropDown

Class gtk:drop-down
Superclasses:
Documented Subclasses:
None
Direct Slots:
enable-search
The enable-search property of type :boolean (Read / Write)
Whether to show a search entry in the popup. Note that search requires the expression property to be set.
Default value: false
expression
The expression property of type gtk:expression (Read / Write)
An expression to evaluate to obtain strings to match against the search term See the enable-search property. If the factory property is not set, the expression is also used to bind strings to labels produced by a default factory.
factory
The factory property of type gtk:list-item-factory (Read / Write)
Factory for populating list items.
header-factory
The header-factory property of type gtk:list-item-factory (Read / Write)
The factory for creating header widgets for the popup. Since 4.12
list-factory
The list-factory property of type gtk:list-item-factory (Read / Write)
The factory for populating list items in the popup. If this is not set, the factory property is used.
model
The model property of type g:list-model (Read / Write)
Model for the displayed items.
search-match-mode
The search-match-mode property of type gtk:string-filter-match-mode (Read / Write)
The match mode for the search filter. Since 4.12
selected
The selected property of type :uint (Read / Write)
The position of the selected item in model, or gtk:+invalid-list-position+ if no item is selected.
Default value: gtk:+invalid-list-position+
selected-item
The selected-item property of type g:object (Read)
The selecte item.
show-arrow
The show-arrow property of type :boolean (Read / Write)
Whether to show an arrow within the GtkDropDown widget. Since 4.6
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:drop-down widget is a widget that allows the user to choose an item from a list of options. The gtk:drop-down widget displays the selected choice.

The options are given to the gtk:drop-down widget in the form of a g:list-model object, and how the individual options are represented is determined by a gtk:list-item-factory object. The default factory displays simple strings.

The gtk:drop-down widget knows how to obtain strings from the items in a gtk:string-list object. For other models, you have to provide an expression to find the strings via the gtk:drop-down-expression function.

The gtk:drop-down widget can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use the gtk:drop-down-enable-search function.
CSS nodes:
The gtk:drop-down implementation has a single CSS node with name dropdown, with the button and popover nodes as children.
Accessibility:
The gtk:drop-down implementation uses the :combo-box role of the gtk:accessible-role enumeration.
Signals:
The "activate" signal
lambda (dropdown)    :action      
The signal is an action signal and emitting it causes the drop down to pop up its dropdown. The default handler is called before the handlers. Since 4.6
dropdown
The gtk:drop-down widget.
See also:
2024-1-10
Syntax:
(gtk:drop-down-enable-search object) => setting
(setf (gtk:drop-down-enable-search object) setting)
Arguments:
object -- a gtk:drop-down widget
setting -- a boolean whether to enable search
Details:
Accessor of the enable-search slot of the gtk:drop-down class. The gtk:drop-down-enable-search function returns whether search is enabled. The (setf drop-down-enable-search) function sets whether a search entry will be shown in the popup that allows to search for items in the list. Note that the expression property must be set for search to work.
See also:
2024-1-10
Accessor gtk:drop-down-expression (object)
Syntax:
(gtk:drop-down-expression object) => expression
(setf (gtk:drop-down-expression object) expression)
Arguments:
object -- a gtk:drop-down widget
expression -- a gtk:expression object, or nil
Details:
Accessor of the expression slot of the gtk:drop-down class. The gtk:drop-down-expression function gets the expression. The (setf drop-down-expression) function sets the expression that gets evaluated to obtain strings from items when searching in the popup. The expression must have a value type of "gchararray".
See also:
2024-1-10
Accessor gtk:drop-down-factory (object)
Syntax:
(gtk:drop-down-factory object) => factory
(setf (gtk:drop-down-factory object) factory)
Arguments:
object -- a gtk:drop-down widget
factory -- a gtk:list-item-factory object, or nil for none
Details:
Accessor of the factory slot of the gtk:drop-down class. The gtk:drop-down-factory function gets the factory that is currently used to populate list items. The (setf drop-down-factory) function sets the factory to use for populating list items. The factory is always used for the item in the button. It is also used for items in the popup if the list-factory property is not set.
See also:
2024-1-10
Accessor gtk:drop-down-header-factory (object)
Syntax:
(gtk:drop-down-header-factory object) => factory
(setf (gtk:drop-down-header-factory object) factory)
Arguments:
object -- a gtk:drop-down widget
factory -- a gtk:list-item-factory object, or nil for none
Details:
Accessor of the header-factory slot of the gtk:drop-down class. The gtk:drop-down-header-factory function sets the factory that is currently used to create header widgets for the popup. The (setf drop-down-header-factory) function sets the factory.

Since 4.12
See also:
2024-1-10
Accessor gtk:drop-down-list-factory (object)
Syntax:
(gtk:drop-down-list-factory object) => factory
(setf (gtk:drop-down-list-factory object) factory)
Arguments:
object -- a gtk:drop-down widget
factory -- a gtk:list-item-factory object, or nil for none
Details:
Accessor of the list-factory slot of the gtk:drop-down class. The gtk:drop-down-list-factory function gets the factory that is currently used to populate list items in the popup. The (setf drop-down-list-factory) function sets the factory to use for populating list items in the popup.
See also:
2024-1-10
Accessor gtk:drop-down-model (object)
Syntax:
(gtk:drop-down-model object) => model
(setf (gtk:drop-down-model object) model)
Arguments:
object -- a gtk:drop-down widget
model -- a g:list-model object to use, or nil for none
Details:
Accessor of the model slot of the gtk:drop-down class. The gtk:drop-down-model function gets the model that provides the displayed items. The (setf drop-down-model) function sets the model to use.
See also:
2024-1-10
Accessor gtk:drop-down-search-match-mode (object)
Syntax:
(gtk:drop-down-search-match-mode object) => mode
(setf (gtk:drop-down-search-match-mode object) mode)
Arguments:
object -- a gtk:drop-down widget
mode -- a gtk:string-filter-match-mode value with the match mode
Details:
Accessor of the search-match-mode slot of the gtk:drop-down class. The gtk:drop-down-search-match-mode function returns the match mode that the search filter is using. The (setf drop-down-search-match-mode) function sets the match mode for the search filter.

Since 4.12
See also:
2024-1-10
Accessor gtk:drop-down-selected (object)
Syntax:
(gtk:drop-down-selected object) => selected
(setf (gtk:drop-down-selected object) selected)
Arguments:
object -- a gtk:drop-down widget
selected -- an unsigned integer with the position of the item to select, or the gtk:+invalid-list-position+ value if no position is selected
Details:
Accessor of the selected slot of the gtk:drop-down class. The gtk:drop-down-selected function gets the position of the selected item. The (setf drop-down-selected) function selects the item at the given position.
See also:
2024-1-10
Accessor gtk:drop-down-selected-item (object)
Syntax:
(gtk:drop-down-selected-item object) => item
Arguments:
object -- a gtk:drop-down widget
item -- A pointer to the selected item.
Details:
Accessor of the selected-item slot of the gtk:drop-down class. The gtk:drop-down-selected-item function gets the selected item. If no item is selected, cffi:null-pointer is returned.
See also:
2024-1-10
Accessor gtk:drop-down-show-arrow (object)
Syntax:
(gtk:drop-down-show-arrow object) => setting
(setf (gtk:drop-down-show-arrow object) setting)
Arguments:
object -- a gtk:drop-down widget
setting -- a boolean whether to show an arrow within the widget
Details:
Accessor of the show-arrow slot of the gtk:drop-down class. The gtk:drop-down-show-arrow function returns whether to show an arrow within the widget. The (setf drop-down-show-arrow) function sets whether an arrow will be displayed.

Since 4.6
See also:
2024-1-10
Function gtk:drop-down-new (model expression)
Arguments:
model -- a g:list-model object to use, or nil for none
expression -- a gtk:expression instance to use, or nil for none
Returns:
The new gtk:drop-down widget.
Details:
Creates a new gtk:drop-down widget. You may want to call the (setf gtk:drop-down-factory) function to set up a way to map its items to widgets.
See also:
2024-8-16
Function gtk:drop-down-new-from-strings (strings)
Arguments:
strings -- a list of strings to put in the dropdown
Returns:
The new gtk:drop-down widget.
Details:
Creates a new dropdown widget that is populated with the strings in strings.
See also:
2024-1-10

Tree support

GtkTreeListModel

Class gtk:tree-list-row
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
children
The children property of type g:list-model (Read)
The model holding the children of the row.
depth
The depth property of type :uint (Read)
The depth in the tree of this row.
Default value: 0
expandable
The expandable property of type :boolean (Read)
Whether the row can ever be expanded.
Default value: false
expanded
The expanded property of type :boolean (Read / Write)
Whether the row is currently expanded.
Default value: false
item
The item property of type g:object (Read)
The item held in this row.
Slot Access Functions:
Details:
The gtk:tree-list-row object is used by the gtk:tree-list-model object to represent items. It allows navigating the model as a tree and modify the state of rows.

The gtk:tree-list-row instances are created by a gtk:tree-list-model object only when the passthrough property is not set.

There are various support objects that can make use of gtk:tree-list-row objects, such as the gtk:tree-expander widget that allows displaying an icon to expand or collapse a row or the gtk:tree-list-row-sorter object that makes it possible to sort trees properly.
See also:
2024-10-17
Accessor gtk:tree-list-row-children (object)
Syntax:
(gtk:tree-list-row-children object) => children
Arguments:
object -- a gtk:tree-list-row object
children -- a g:list-model object containing the children
Details:
Accessor of the children slot of the gtk:tree-list-row class. If the row is expanded, the gtk:tree-list-row-children function gets the model holding the children of model. This is the model created by the gtk:tree-list-model-create-model-func callback function and contains the original items, no matter what value the passthrough property is set to.
See also:
2024-10-17
Accessor gtk:tree-list-row-depth (object)
Syntax:
(gtk:tree-list-row-depth object) => depth
Arguments:
object -- a gtk:tree-list-row object
depth -- an unsigned integer with the depth of the row
Details:
Accessor of the depth slot of the gtk:tree-list-row class. The gtk:tree-list-row-depth function gets the depth of the row. Rows that correspond to items in the root model have a depth of zero, rows corresponding to items of models of direct children of the root model have a depth of 1 and so on. The depth of a row never changes until the row is removed from its model at which point it will forever return 0.
See also:
2024-10-17
Accessor gtk:tree-list-row-expandable (object)
Syntax:
(gtk:tree-list-row-expandable object) => expandable
Arguments:
object -- a gtk:tree-list-row object
expandable -- a boolean whether the row can ever be expanded
Details:
Accessor of the expandable slot of the gtk:tree-list-row class. The gtk:tree-list-row-expandable function gets whether the row can ever be expanded.
See also:
2024-10-17
Accessor gtk:tree-list-row-expanded (object)
Syntax:
(gtk:tree-list-row-expanded object) => expanded
Arguments:
object -- a gtk:tree-list-row object
expanded -- a boolean whether the row is currently expanded
Details:
Accessor of the expanded slot of the gtk:tree-list-row class. The gtk:tree-list-row-expanded function gets if a row is currently expanded.
See also:
2024-10-17
Accessor gtk:tree-list-row-item (object)
Syntax:
(gtk:tree-list-row-item object) => item
Arguments:
object -- a gtk:tree-list-row object
item -- a g:object instance with the item held in this list row
Details:
Accessor of the item slot of the gtk:tree-list-row class. The gtk:tree-list-row-item function gets the item corresponding to this list row.
See also:
2024-10-29
Function gtk:tree-list-row-child-row (listrow pos)
Arguments:
listrow -- a gtk:tree-list-row object
pos -- an unsigned integer with the position of the child to get
Returns:
The gtk:tree-list-row object with the child in pos.
Details:
If listrow is not expanded or pos is greater than the number of children, nil is returned.
See also:
#2024-10-29
Function gtk:tree-list-row-parent (listrow)
Arguments:
listrow -- a gtk:tree-list-row object
Returns:
The parent gtk:tree-list-row object.
Details:
Gets the list row representing the parent for listrow. That is the list row that would need to be collapsed to make this list row disappear. If listrow is a list row corresponding to the root model, nil is returned. The value returned by this function never changes until the list row is removed from its model at which point it will forever return nil.
See also:
2024-10-29
Function gtk:tree-list-row-position (listrow)
Arguments:
listrow -- a gtk:tree-list-row object
Returns:
The unsigned integer with the position in the model.
Details:
Returns the position in the model that listrow occupies at the moment.
See also:
#2024-10-29
Function gtk:tree-list-row-is-expandable (listrow)
Arguments:
listrow -- a gtk:tree-list-row object
Returns:
True if the row is expandable.
Details:
Checks if a row can be expanded. This does not mean that the row is actually expanded, this can be checked with the gtk:tree-list-row-expanded function. If a row is expandable never changes until the row is removed from its model at which point it will forever return false.
See also:
#2024-10-29
Class gtk:tree-list-model
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
autoexpand
The autoexpand property of type :boolean (Read / Write)
If all rows should be expanded by default.
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
model
The model property of type g:list-model (Read)
The root model displayed.
n-items
The n-items property of type :uint(Read / Write)
The number of items. Since 4.8
Default value: 0
passthrough
The passthrough property of type :boolean (Read / Write / Construct only)
If false, the g:list-model functions for this object return custom gtk:tree-list-row objects. If true, the values of the child models are passed through unmodified.
Returned by:
Slot Access Functions:
Details:
The gtk:tree-list-model object is a list model that can create child models on demand.
2024-10-17
Accessor gtk:tree-list-model-autoexpand (object)
Syntax:
(gtk:tree-list-model-autoexpand object) => autoexpand
(setf (gtk:tree-list-model-autoexpand object) autoexpand)
Arguments:
object -- a gtk:tree-list-model object
autoexpand -- true if the model is set to autoexpand
Details:
Accessor of the autoexpand slot of the gtk:tree-list-model class. The gtk:tree-list-model-autoexpand function gets whether the model is set to automatically expand new rows that get added.

If set to true with the (setf gtk:tree-list-model-autoexpand) function, the model will recursively expand all rows that get added to the model. This can be either rows added by changes to the underlying models or via the gtk:tree-list-row-expanded function.
See also:
2024-10-17
Accessor gtk:tree-list-model-item-type (object)
Syntax:
(gtk:tree-list-model-item-type object) => gtype
Arguments:
object -- a gtk:tree-list-model object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the gtk:tree-list-model class. The type of items contained in the list model. Items must be subclasses of the g:object class.

Since 4.8
Notes:
This function is equivalent to the g:list-model-item-type function.
See also:
2024-12-22
Accessor gtk:tree-list-model-model (object)
Syntax:
(gtk:tree-list-model-model object) => model
Arguments:
object -- a gtk:tree-list-model object
model -- a g:list-model object root model
Details:
Accessor of the model slot of the gtk:tree-list-model class. The gtk:tree-list-model-model function gets the root model that object was created with.
See also:
2024-10-17
Accessor gtk:tree-list-model-n-items (object)
Syntax:
(gtk:tree-list-model-n-items object) => n-items
Arguments:
object -- a gtk:tree-list-model object
n-items -- an unsigned integer with the number of items contained in the model
Details:
Accessor of the n-items slot of the gtk:tree-list-model class.
See also:
2024-10-17
Accessor gtk:tree-list-model-passthrough (object)
Syntax:
(gtk:tree-list-model-passthrough object) => passthrough
Arguments:
object -- a gtk:tree-list-model object
passthrough -- true if the model is passing through original row items
Details:
Accessor of the passthrough slot of the gtk:tree-list-model class. If the gtk:tree-list-model-passthrough function returns false, the g:list-model functions for object return custom gtk:tree-list-row objects. You need to call the gtk:tree-list-row-item function on these objects to get the original item.

If true, the values of the child models are passed through in their original state. You then need to call the gtk:tree-list-model-row function to get the custom gtk:tree-list-row objects.
See also:
2024-10-17
Callback gtk:tree-list-model-create-model-func
Syntax:
lambda (object) => result
Arguments:
object -- a g:object instance with the item that is being expanded
result -- a g:list-model object tracking the children of object or nil if object can never have children
Details:
Prototype of the function called to create new child models when the gtk:tree-list-row-expanded function is called. This function can return nil to indicate that object is guaranteed to be a leaf node and will never have children. If it does not have children but may get children later, it should return an empty model that is filled once children arrive.
See also:
2024-3-30
Function gtk:tree-list-model-new (root passthrough autoexpand func)
Arguments:
root -- a g:list-model object to use as root
passthrough -- true to pass through items from the models
autoexpand -- true to set the autoexpand property and expand the root model
func -- a gtk:tree-list-model-create-model-func callback function to create the g:list-model object for the children of an item
Details:
Creates a new empty gtk:tree-list-model object displaying root with all rows collapsed.
See also:
2024-3-30
Function gtk:tree-list-model-row (model position)
Arguments:
model -- a gtk:tree-list-model object
position -- an unsigned integer with the position of the row to fetch
Returns:
The gtk:tree-list-row object with the row item.
Details:
Gets the row object for the given row. If position is greater than the number of items in model, nil is returned. The row object can be used to expand and collapse rows as well as to inspect its position in the tree. See its documentation for details.

This row object is persistent and will refer to the current item as long as the row is present in model, independent of other rows being added or removed. If model is set to not be passthrough, this function is equivalent to calling the g:list-model-item function. Do not confuse this function with the gtk:tree-list-model-child-row function.
See also:
#2023-9-24
Function gtk:tree-list-model-child-row (model position)
Arguments:
model -- a gtk:tree-list-model object
position -- an unsigned integer with the position of the child to get
Returns:
The gtk:tree-list-row object with the child in position.
Details:
Gets the row item corresponding to the child at index position for model's root model. If position is greater than the number of children in the root model, nil is returned. Do not confuse this function with the gtk:tree-list-model-row function.
See also:
#2023-9-24

GtkTreeListRowSorter

Class gtk:tree-list-row-sorter
Superclasses:
gtk:sorter, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
sorter
The sorter property of type gtk:sorter (Read / Write)
The underlying sorter.
Returned by:
Slot Access Functions:
Details:
The gtk:tree-list-row-sorter object is a special-purpose sorter that will apply a given sorter to the levels in a tree, while respecting the tree structure.
Examples:
Here is an example for setting up a column view with a tree model and a gtk:tree-list-sorter object:
column_sorter = gtk_column_view_get_sorter (view);
sorter = gtk_tree_list_row_sorter_new (g_object_ref (column_sorter));
sort_model = gtk_sort_list_model_new (tree_model, sorter);
selection = gtk_single_selection_new (sort_model);
gtk_column_view_set_model (view, G_LIST_MODEL (selection));    
See also:
#2023-9-10
Accessor gtk:tree-list-row-sorter-sorter (object)
Syntax:
(gtk:tree-list-row-sorter-sorter object) => sorter
(setf (gtk:tree-list-row-sorter-sorter object) sorter)
Arguments:
object -- a gtk:tree-list-row-sorter object
sorter -- a gtk:sorter object to use, or nil
Details:
Accessor of the sorter slot of the gtk:tree-list-row-sorter class. The gtk:tree-list-row-sorter-sorter function returns the sorter used by object. The (setf gtk:tree-list-row-sorter-sorter) function sets the sorter to use for items with the same parent. This sorter will be passed the item of the tree list rows passed to object.
See also:
#2023-9-10
Function gtk:tree-list-row-sorter-new (sorter)
Arguments:
sorter -- a gtk:sorter object
Returns:
The new gtk:tree-list-row-sorter object.
Details:
Create a special-purpose sorter that applies the sorting of sorter to the levels of a gtk:tree-list-model object. Note that this sorter relies on the passthrough property being false as it can only sort gtk:tree-list-row objects.
See also:
#2023-9-26

GtkTreeExpander

Class gtk:tree-expander
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget with the actual contents.
hide-expander
The hide-expander property of type :boolean (Read / Write)
Whether the expander icon should be hidden in a gtk:tree-list-row object. Note that this property simply hides the icon. The actions and keybinding, that is, collapse and expand, are not affected by this property. A common use for this property would be to bind to the number of children in the model of a gtk:tree-list-row object, to hide the expander when a row has no children. Since 4.10
Default value: false
indent-for-depth
The indent-for-depth property of type :boolean (Read / Write)
The tree expander indents the child according to its depth. Since 4.10
Default value: true
indent-for-icon
The indent-for-icon property of type :boolean (Read / Write)
The tree expander indents the child by the width of an expander-icon if it is not expandable. Since 4.6
Default value: true
item
The item property of type g:object (Read)
The item held by this expander’s row.
list-row
The list-row property of type gtk:tree-list-row (Read / Write)
The list row to track for expander state.
Returned by:
Slot Access Functions:
Details:
The gtk:tree-expander widget is a widget that provides an expander for a list. It is typically placed as a bottommost child into a gtk:list-view widget to allow users to expand and collapse children in a list with a gtk:tree-list-model object. The gtk:tree-expander widget provides the common UI elements, gestures and keybindings for this purpose.

On top of this, the "listitem.expand", "listitem.collapse" and "listitem.toggle-expand" actions are provided to allow adding custom UI for managing expanded state.

It is important to mention that you want to set the focusable property to false when using this widget, as you want the keyboard focus to be in the treexpander, and not inside the list to make use of the keybindings.

The gtk:tree-list-model object must be set to not be passthrough. Then it will provide gtk:tree-list-row items which can be set via the gtk:tree-expander-list-row function on the expander. The expander will then watch that row item automatically. The gtk:tree-expander-child function sets the widget that displays the actual row contents.

The gtk:tree-expander widget can be modified with properties such as indent-for-icon, indent-for-depth, and hide-expander properties to achieve a different appearance. This can even be done to influence individual rows, for example by binding the hide-expander property to the item count of the model of the treelistrow, to hide the expander for rows without children, even if the row is expandable.
CSS nodes:
The gtk:tree-expander implementation has zero or one CSS nodes with the name expander that should display the expander icon. The node will be :checked when it is expanded. If the node is not expandable, an indent node will be displayed instead. For every level of depth, another indent node is prepended.
Accessibility:
Until GTK 4.10, the gtk:tree-expander implementation used the :group role. Since GTK 4.12, the gtk:tree-expander implementation uses the :button role of the gtk:accessible-role enumeration. Toggling it will change the :expanded value of the gtk:accessible-state enumeration.
See also:
#2023-9-10
Accessor gtk:tree-expander-child (object)
Syntax:
(gtk:tree-expander-child object) => child
(setf (gtk:tree-expander-child object) child)
Arguments:
object -- a gtk:tree-expander object
child -- a gtk:widget object
Details:
Accessor of the child slot of the gtk:tree-expander class. The gtk:tree-expander-child function gets the child widget displayed by object. The (setf gtk:tree-expander-child) function sets the content widget to display.
See also:
#2023-9-26
Accessor gtk:tree-expander-hide-expander (object)
Syntax:
(gtk:tree-expander-hide-expander object) => setting
(setf (gtk:tree-expander-hide-expander object) setting)
Arguments:
object -- a gtk:tree-expander object
setting -- a boolean whether the expander icon should be hidden
Details:
Accessor of the hide-expander slot of the gtk:tree-expander class. The gtk:tree-expander-hide-expander function gets whether the tree expander should be hidden in a gtk:tree-list-row object. The (setf gtk:tree-expander-hide-expander) function sets whether the expander icon should be visible in a gtk:tree-list-row object.

Since 4.10
See also:
#2023-9-26
Accessor gtk:tree-expander-indent-for-depth (object)
Syntax:
(gtk:tree-expander-indent-for-depth object) => setting
(setf (gtk:tree-expander-indent-for-depth object) setting)
Arguments:
object -- a gtk:tree-expander object
setting -- a boolean whether the expander indents the child according to its depth
Details:
Accessor of the indent-for-depth slot of the gtk:tree-expander class. The gtk:tree-expander-indent-for-depth function gets whether the tree expander indents each level of depth with an additional indent. The (setf gtk:tree-expander-indent-for-depth) function sets if the tree expander should indent the child according to its depth.

Since 4.10
See also:
#2023-9-26
Accessor gtk:tree-expander-indent-for-icon (object)
Syntax:
(gtk:tree-expander-indent-for-icon object) => setting
(setf (gtk:tree-expander-indent-for-icon object) setting)
Arguments:
object -- a gtk:tree-expander object
setting -- true if the child should be indented without expander, otherwise false
Details:
Accessor of the indent-for-icon slot of the gtk:tree-expander class. The gtk:tree-expander-indent-for-icon function gets whether the tree expander indents the child by the width of an expander-icon if it is not expandable. The (setf gtk:tree-expander-indent-for-icon) function sets whether the tree expander should indent the child by the width of an expander-icon when it is not expandable.

Since 4.6
See also:
#2023-9-26
Accessor gtk:tree-expander-item (object)
Syntax:
(gtk:tree-expander-item object) => item
Arguments:
object -- a gtk:tree-expander object
item -- a g:object instance with the item of the row
Details:
Accessor of the item slot of the gtk:tree-expander class. The gtk:tree-expander-item function forwards the item set on the gtk:tree-list-row object that object is managing. This call is essentially equivalent to calling:
(gtk:tree-list-row-item (gtk:tree-expander-list-row object))  
See also:
#2023-9-26
Accessor gtk:tree-expander-list-row (object)
Syntax:
(gtk:tree-expander-list-row object) => row
(setf (gtk:tree-expander-list-row object) row)
Arguments:
object -- a gtk:tree-expander object
row -- a gtk:tree-list-row object
Details:
Accessor of the list-row slot of the gtk:tree-expander class. The gtk:tree-expander-list-row function gets the list row managed by object. The (setf gtk:tree-expander-list-row) function sets the tree list row that this expander should manage.
See also:
#2023-9-26
Function gtk:tree-expander-new ()
Returns:
The new gtk:tree-expander widget.
Details:
Creates a new tree expander.
See also:
#2023-9-26

Application support

GtkApplication

GFlags gtk:application-inhibit-flags
Declaration:
(gobject:define-gflags "GtkApplicationInhibitFlags" application-inhibit-flags
  (:export t
   :type-initializer "gtk_application_inhibit_flags_get_type")
  (:logout  #.(ash 1 0))
  (:switch  #.(ash 1 1))
  (:suspend #.(ash 1 2))
  (:idle    #.(ash 1 3)))  
Values:
:logout
Inhibit ending the user session by logging out or by shutting down the computer.
:switch
Inhibit user switching.
:suspend
Inhibit suspending the session or computer.
:idle
Inhibit the session being marked as idle and possibly locked.
Details:
Types of user actions that may be blocked by a gtk:application instance. See the gtk:application-inhibit function.
See also:
2024-10-7
Class gtk:application
Superclasses:
gio:application, gio:action-group, gio:action-map, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
active-window
The active-window property of type gtk:window (Read)
The currently focused window of the application.
menubar
The menubar property of type g:menu-model (Read / Write)
The menu model to be used for the menubar of the application.
register-session
The register-session property of type :boolean (Read / Write)
Set the property to true to register with the session manager.
Default value: false
screensaver-active
The screensaver-active property of type :boolean (Read)
The property is true if GTK believes that the screensaver is currently active. GTK only tracks session state, when the register-session property is set to true. Tracking the screensaver state is supported on Linux.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:application class is a high-level API for writing applications. It supports many aspects of a GTK application in a convenient fashion, without enforcing a one-size-fits-all application model.

Currently, the gtk:application class handles GTK initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life cycle is automatically tied to the life cycle of the application.

While the gtk:application class works fine with plain gtk:window widgets, it is recommended to use it together with gtk:application-window widgets.

Automatic resources
The gtk:application instance will automatically load menus from the gtk:builder resource located at "gtk/menus.ui", relative to the resource base path of the application, see the g:application-resource-base-path function. The menu with the ID "menubar" is taken as the menubar of the application. Additional menus, most interesting submenus, can be named and accessed via the gtk:application-menu-by-id function which allows for dynamic population of a part of the menu structure. It is also possible to provide the menubar manually using the gtk:application-menubar function.

The gtk:application instance will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See the gtk:icon-theme-add-resource-path function for more information.

If there is a resource located at "gtk/help-overlay.ui" which defines a gtk:shortcuts-window widget with ID "help_overlay" then the gtk:application instance associates an instance of this shortcuts window with each gtk:application-window widget and sets up keyboard accelerators, Control-F1 and Control-?, to open it. To create a menu item that displays the shortcuts window, associate the menu item with the "win.show-help-overlay" action.

The gtk:application instance optionally registers with a session manager of the users session, if you set the register-session property, and offers various functionality related to the session life cycle.

An application can block various ways to end the session with the gtk:application-inhibit function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present.
Examples:
A simple application:
(defun application-simple (&rest argv)
  (let (;; Create an application
        (app (make-instance 'gtk:application
                            :flags :default-flags
                            :application-id "com.crategus.application-simple")))
    ;; Connect signal "activate" to the application
    (g:signal-connect app "activate"
        (lambda (application)
          (g:application-hold application)
          ;; Create an application window
          (let ((window (make-instance 'gtk:application-window
                                       :application application
                                       :title "Simple Application"
                                       :default-width 480
                                       :default-height 300)))
            ;; Present the application window
            (gtk:window-present window)
            (g:application-release application))))
  ;; Run the application
  (g:application-run app argv)))    
A resource definition with menus, a shortcuts window and an icon for automatically loading resources:
<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/com/crategus/application/gtk">
    <file>menus.ui</file>
    <file>help-overlay.ui</file>
  </gresource>
  <gresource prefix="/com/crategus/application/icons">
    <file>my-gtk-logo.png</file>
  </gresource>
</gresources>    
The application that automatically loads the resources:
(defun application-resources (&rest argv)
  ;; Register the resources
  (g:with-resource (resource (glib-sys:check-and-create-resources
                                     "gtk4-application.xml"
                                     :package "gtk4-application"
                                     :sourcedir "resource/"))
    (let (;; Create an application
          (app (make-instance 'gtk:application
                               :flags :default-flags
                               :application-id
                               "com.crategus.application")))
      ;; Connect "activate" signal
      (g:signal-connect app "activate"
          (lambda (application)
            (g:application-hold application)
            ;; Create an application window
            (let (;; Define action entries for the menu items
                  (entries '(("about")))
                  (accels '("win-show-help-overlay" "F1"
                            "win.about" "<Control>A"))
                  (window (make-instance 'gtk:application-window
                                         :application application
                                         :title "Application Resources"
                                         :show-menubar t
                                         :icon-name "gtk-logo"
                                         :default-width 480
                                         :default-height 300)))
              ;; Add accelerators for the application
              (iter (for (name accel) on accels by #'cddr)
                    (setf (gtk:application-accels-for-action application name)
                          accel))
              ;; Add the action entries to the application window
              (g:action-map-add-action-entries window entries)
              ;; Present the window
              (gtk:window-present window)
              (g:application-release application))))
      ;; Run the application
      (g:application-run app argv))))    
Signal Details:
The "query-end" signal
lambda (application)    :run-first      
application
The gtk:application instance which emitted the signal.
Emitted when the session manager is about to end the session. This signal is only emitted if the register-session property is true. Applications can connect to this signal and call the gtk:application-inhibit function with the :logout value of the gtk:application-inhibit-flags flags to delay the end of the session until the state has been saved.
The "window-added" signal
lambda (application window)    :run-first      
application
The gtk:application instance which emitted the signal.
window
The newly added gtk:window widget.
Emitted when a gtk:window widget is added to the application through the gtk:application-add-window function.
The "window-removed" signal
lambda (application window)    :run-first      
application
The gtk:application instance which emitted the signal.
window
The gtk:window widget that is being removed.
Emitted when a gtk:window widget is removed from the application. This can happen as a side-effect of the window being destroyed or explicitly through the gtk:application-remove-window function.
See also:
2024-10-7
Accessor gtk:application-active-window (object)
Syntax:
(gtk:application-active-window object) => window
Arguments:
object -- a gtk:application instance
window -- a gtk:window widget
Details:
Accessor of the active-window slot of the gtk:application class. The gtk:application-active-window function gets the active window for the application. The active window is the one that was most recently focused within the application. This window may not have the focus at the moment if another application has it - this is just the most recently focused window within this application.
See also:
2024-10-7
Accessor gtk:application-menubar (object)
Syntax:
(gtk:application-menubar object) => menubar
(setf (gtk:application-menubar object) menubar)
Arguments:
object -- a gtk:application instance
menubar -- a g:menu-model object, or nil
Details:
Accessor of the menubar slot of the gtk:application class. The gtk:application-menubar function returns the menubar for windows of the application. The (setf gtk:application-menubar) function sets or unsets the menubar.

This is a menubar in the traditional sense. This can only be done in the primary instance of the application, after it has been registered. The handler for the "startup" signal is a good place to set the menubar.

Depending on the desktop environment, the menubar may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate - for example, the application menu may be rendered by the desktop shell while the menubar, if set, remains in each individual window.

Use the base g:action-map interface to add actions, to respond to the user selecting these menu items.
See also:
2024-10-7
Accessor gtk:application-register-session (object)
Syntax:
(gtk:application-register-session object) => setting
(setf (gtk:application-register-session object) setting)
Arguments:
object -- a gtk:application instance
setting -- a boolean whether to register with the session manager
Details:
Accessor of the register-session slot of the gtk:application class. Set the register-session property to true to register with the session mananger. This will make GTK track the session state, such as the screensaver-active property.
See also:
2024-10-7
Accessor gtk:application-screensaver-active (object)
Syntax:
(gtk:application-screensaver-active object) => active
Arguments:
object -- a gtk:application instance
active -- a boolean whether the screensaver is active
Details:
Accessor of the screensaver-active slot of the gtk:application class. The screensaver-active property is true if GTK believes that the screensaver is currently active. GTK only tracks session state, including this, when the register-session property is set to true. Tracking the screensaver state is supported on Linux.
See also:
2024-10-7
Function gtk:application-new (id flags)
Arguments:
id -- a string with the application ID, or nil for no application ID
flags -- a g:application-flags value with the application flags
Returns:
The new gtk:application instance.
Details:
Creates a new application. When using the gtk:application class, it is not necessary to call the gtk:init function manually. It is called as soon as the application gets registered as the primary instance.

Concretely, the gtk:init function is called in the default handler for the "GApplication::startup" signal. Therefore, gtk:application subclasses should always chain up in their "GApplication::startup" handler before using any GTK API. Note that commandline arguments are not passed to the gtk:init function.

The application ID must be valid. See the g:application-id-is-valid function. If no application ID is given then some features, most notably application uniqueness, will be disabled.
See also:
2024-10-7
Function gtk:application-add-window (application window)
Arguments:
application -- a gtk:application instance
window -- a gtk:window widget
Details:
Adds a window to the application. This call can only happen after the application has started. Typically, you should add new application windows in response to the emission of the "GApplication::activate" signal. This call is equivalent to setting the application property of the given window to the given application, that is:
(gtk:application-add-window application window)
== (setf (gtk:window-application window) application)  
Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with the gtk:application-remove-window function. GTK will keep the application running as long as it has any windows.
See also:
2024-10-7
Function gtk:application-remove-window (application window)
Arguments:
application -- a gtk:application instance
window -- a gtk:window widget
Details:
Remove a window from the application. If the window argument belongs to the given application then this call is equivalent to setting the application property of window to nil, that is:
(gtk:application-remove-window application window)
== (setf (gtk:window-application window) nil)  
The application may stop running as a result of a call to this function, if the window argument was the last window of the application.
See also:
2024-10-7
Function gtk:application-windows (application)
Arguments:
application -- a gtk:application instance
Returns:
The list of gtk:window widgets.
Details:
Gets a list of the windows associated with the application. The list is sorted by most recently focused windows, such that the first element is the currently focused window. This is useful for choosing a parent for a transient window.
Examples:
In this example, the function iterates over the list of windows and destroys the windows. After the last window is destroyed, the application quits.
(defun action-quit (application action parameter)
  (declare (ignore action parameter))
  (let ((windows (gtk:application-windows application)))
    (dolist (window windows)
      (gtk:window-destroy window))))    
See also:
2024-10-7
Function gtk:application-window-by-id (application id)
Arguments:
application -- a gtk:application instance
id -- an unsigned integer identifier number
Returns:
The gtk:application-window widget with ID id, or nil if there is no window with this ID.
Details:
Returns the application window with the given ID. The ID of an application window can be retrieved with the gtk:application-window-id function.
Notes:
Both gtk:window and gtk:application-window widgets can be added to an application, but only a gtk:application-window widget has an ID.
See also:
2024-10-7
Function gtk:application-inhibit (application window flags reason)
Arguments:
application -- a gtk:application instance
window -- a gtk:window widget, or nil
flags -- a gtk:application-inhibit-flags value with the types of user actions that should be inhibited
reason -- a short, human readable string that explains why these operations are inhibited
Returns:
The non-zero unsigned integer cookie that is used to uniquely identify this request. It should be used as an argument to the gtk:application-uninhibit function in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned.
Details:
Inform the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions.

Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the flags argument. When the application completes the operation it should call the gtk:application-uninhibit function to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits.

Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place.

Reasons should be short and to the point.

If the window argument is given, the session manager may point the user to this window to find out more about why the action is inhibited.
See also:
2024-10-7
Function gtk:application-uninhibit (application cookie)
Arguments:
application -- a gtk:application instance
cookie -- an unsigned integer cookie that was returned by the gtk:application-inhibit function
Details:
Removes an inhibitor that has been established with the gtk:application-inhibit function. Inhibitors are also cleared when the application exits.
See also:
2024-10-7
Function gtk:application-menu-by-id (application id)
Arguments:
application -- a gtk:application instance
id -- a string with the ID of the menu to look up
Returns:
Gets the g:menu object with the given id argument from the automatically loaded resources.
Details:
Gets a menu from automatically loaded resources.
See also:
2024-10-7
Function gtk:application-list-action-descriptions (application)
Arguments:
application -- a gtk:application instance
Returns:
The list of strings with the detailed action names.
Details:
Lists the detailed action names which have associated accelerators. See the gtk:application-accels-for-action function.
See also:
2024-10-7
Function gtk:application-accels-for-action (application name)
Syntax:
(gtk:application-accels-for-action application name) => accels
(setf (gtk:application-accels-for-action application name) accels)
Arguments:
application -- a gtk:application instance
name -- a string with a detailed action name, specifying an action and target
accels -- a string or a list of strings of accelerators in the format understood by the gtk:accelerator-parse function
Details:
The gtk:application-accels-for-action function gets the keyboard accelerators that will trigger the given action. The (setf gtk:application-accels-for-action) function sets zero or more keyboard accelerators.

The first item in the list of accelerators will be the primary accelerator, which may be displayed in the UI. To remove all accelerators for an action, use an empty list.

For the detailed action name, see the g:action-parse-detailed-name and g:action-print-detailed-name functions.
See also:
2024-10-7
Function gtk:application-actions-for-accel (application accel)
Arguments:
application -- a gtk:application instance
accel -- a string with an accelerator that can be parsed by the gtk:accelerator-parse function
Returns:
The list of strings of actions for the accel argument.
Details:
Returns the list of actions, possibly empty, that the given accelerator maps to. Each item in the list is a detailed action name in the usual form.

This might be useful to discover if an accelerator already exists in order to prevent installation of a conflicting accelerator, from an accelerator editor or a plugin system, for example. Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context.

In case there are no actions for a given accelerator, an empty list is returned.

It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with the gtk:accelerator-parse function first.
See also:
2024-10-7

GtkApplicationWindow

Class gtk:application-window
Superclasses:
Documented Subclasses:
None
Direct Slots:
show-menubar
The show-menubar property of type :boolean (Read / Write / Construct)
If this property is true, the application window will display a menubar unless it is shown by the desktop shell. If false, the applicaton window will not display a menubar, regardless of whether the desktop shell is showing it or not.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:application-window class is a gtk:window subclass that offers some extra functionality for better integration with gtk:application features. Notably, it can handle an application menubar.

This class implements the g:action-group and g:action-map interfaces, to let you add window specific actions that will be exported by the associated gtk:application instance, together with its application-wide actions. Window specific actions are prefixed with the "win." prefix and application-wide actions are prefixed with the "app." prefix. Actions must be addressed with the prefixed name when referring to them from a g:menu-model object.

Note that widgets that are placed inside an application window can also activate these actions, if they implement the gtk:actionable interface.

The gtk-shell-shows-app-menu and gtk-shell-shows-menubar settings tell GTK whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely. On Windows neither will be.

If the desktop environment does not display the menubar, then the application window will automatically show a menubar for it. This behaviour can be overridden with the show-menubar property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations.

See the gtk:popover-menu documentation for information about the XML language used by the gtk:builder object for menu models.
Examples:
Create an application window with a menubar.
(defun do-application-window (&optional application)
  (let ((menus
         "<interface>
           <menu id='menubar'>
             <submenu>
               <attribute name='label'>_Edit</attribute>
               <item>
                 <attribute name='label'>_Copy</attribute>
                 <attribute name='action'>win.copy</attribute>
               </item>
               <item>
                 <attribute name='label'>_Paste</attribute>
                 <attribute name='action'>win.paste</attribute>
               </item>
             </submenu>
           </menu>
         </interface>")
        (builder (make-instance 'gtk:builder))
        (window (make-instance 'gtk:application-window
                               :application application
                               :title "Application Window"
                               :show-menubar t)))
    ;; Read the menus from a string
    (gtk:builder-add-from-string builder menus)
    ;; Set the menubar
    (setf (gtk:application-menubar application)
          (gtk:builder-object builder "menubar"))
    ;; Present the application window
    (gtk:window-present window)))    
See also:
2024-10-7
Accessor gtk:application-window-show-menubar (object)
Syntax:
(gtk:application-window-show-menubar object) => show
(setf (gtk:application-window-show-menubar object) show)
Arguments:
window -- a gtk:application-window widget
show -- a boolean whether to show a menubar when needed
Details:
Accessor of the show-menubar slot of the gtk:application-window class. The gtk:application-window-show-menubar function returns whether the window will display a menubar for the application menu and menubar as needed. The (setf gtk:application-window-show-menubar) function sets whether the window will display a menubar.
See also:
2024-10-7
Function gtk:application-window-new (&optional application)
Arguments:
application -- an optinoal gtk:application instance
Returns:
The newly created gtk:application-window widget.
Details:
Creates a new application window. New application windows must be added to an application after the GApplication::startup signal has been emitted. See also the gtk:application-add-window documentation.
See also:
2024-10-7
Function gtk:application-window-id (window)
Arguments:
window -- a gtk:application-window widget
Returns:
The unique ID for window, or 0 if window has not yet been added to a gtk:application instance.
Details:
Returns the unique ID of the application window. If the application window has not yet been added to a gtk:application instance, returns 0.
See also:
2024-10-7
Function gtk:application-window-help-overlay (window)
Syntax:
(gtk:application-window-help-overlay window) => overlay
(setf (gtk:application-window-help-overlay window) overlay)
Arguments:
window -- a gtk:application-window widget
overlay -- a gtk:shortcuts-window widget
Details:
Accessor of the shortcuts window associated with the application window. The gtk:application-window-help-overlay function gets the shortcuts window. The (setf gtk:applicaton-window-help-overlay) function associates a shortcuts window with the application window, and sets up an action with the name "win.show-help-overlay" to present it.

The window takes responsibility for destroying the help overlay.
See also:
2024-10-7

Interface builder

GtkBuildable

Interface gtk:buildable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
gtk:about-dialog, gtk:action-bar, gtk:any-filter, gtk:app-chooser-button, gtk:app-chooser-dialog, gtk:app-chooser-widget, gtk:application-window, gtk:aspect-frame, gtk:assistant, gtk:box, gtk:button, gtk:calendar, gtk:cell-area, gtk:cell-area-box, gtk:cell-view, gtk:center-box, gtk:check-button, gtk:color-button, gtk:color-chooser-dialog, gtk:color-chooser-widget, gtk:color-dialog-button, gtk:column-view, gtk:combo-box, gtk:combo-box-text, gtk:dialog, gtk:drag-icon, gtk:drawing-area, gtk:drop-down, gtk:editable-label, gtk:emoji-chooser, gtk:entry, gtk:entry-completion, gtk:every-filter, gtk:expander, gtk:file-chooser-dialog, gtk:file-chooser-widget, gtk:file-filter, gtk:fixed, gtk:flow-box, gtk:flow-box-child, gtk:font-button, gtk:font-chooser-dialog, gtk:font-chooser-widget, gtk:font-dialog-button, gtk:frame, gtk:gl-area, gtk:graphics-offload, gtk:grid, gtk:grid-view, gtk:header-bar, gtk:icon-view, gtk:image, gtk:info-bar, gtk:inscription, gtk:label, gtk:level-bar, gtk:link-button, gtk:list-base, gtk:list-box, gtk:list-box-row, gtk:list-store, gtk:lock-button, gtk:media-controls, gtk:menu-button, gtk:message-dialog, gtk:multi-filter, gtk:multi-sorter, gtk:notebook, gtk:overlay, gtk:page-setup-unix-dialog, gtk:paned, gtk:password-entry, gtk:picture, gtk:popover, gtk:popover-menu, gtk:popover-menu-bar, gtk:print-unix-dialog, gtk:progress-bar, gtk:range, gtk:revealer, gtk:scale, gtk:scale-button, gtk:scrollbar, gtk:scrolled-window, gtk:search-bar, gtk:search-entry, gtk:separator, gtk:shortcut-controller, gtk:shortcut-label, gtk:shortcuts-group, gtk:shortcuts-section, gtk:shortcuts-shortcut, gtk:shortcuts-window, gtk:size-group, gtk:spin-button, gtk:spinner, gtk:stack, gtk:stack-sidebar, gtk:stack-switcher, gtk:statusbar, gtk:string-list, gtk:switch, gtk:text, gtk:text-tag-table, gtk:text-view, gtk:toggle-button, gtk:tree-expander, gtk:tree-store, gtk:tree-view, gtk:tree-view-column, gtk:video, gtk:viewport, gtk:volume-button, gtk:widget, gtk:window, gtk:window-controls, gtk:window-handle
Direct Slots:
None
Details:
The gtk:buildable interface allows objects to extend and customize their deserialization from gtk:builder UI descriptions. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.

The gtk:buildable interface is implemented by all widgets and many of the non-widget objects that are provided by GTK. The main user of this interface is the gtk:builder class. There should be very little need for applications to call any of these functions directly.

An object only needs to implement this interface if it needs to extend the gtk:builder format or run any extra routines at deserialization time.
See also:
2023-8-7
Function gtk:buildable-buildable-id (buildable)
Arguments:
buildable -- a gtk:buildable object
Returns:
The string with the ID of the buildable object.
Details:
Gets the ID of the buildable object. The gtk:builder object sets the name based on the ID attribute of the tag used to construct the buildable object.
See also:
2024-10-6

GtkBuilder

GFlags gtk:builder-closure-flags
Declaration:
(gobject:define-gflags "GtkBuilderClosureFlags" builder-closure-flags
  (:export t
   :type-initializer "gtk_builder_closure_flags_get_type")
  (:swapped #.(ash 1 0)))  
Values:
:swapped
The closure should be created swapped.
Details:
The list of flags that can be passed to the gtk:builder-create-closure function. New values may be added in the future for new features, so external implementations of the gtk:builder-scope interface should test the flags for unknown values and raise an error when they encounter one.
See also:
gtk:builder
gtk:builder-create-closure
2024-10-5
Interface gtk:builder-scope
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:builder-scope interface is an interface to provide language binding support to the gtk:builder object. The goal of the gtk:builder-scope interface is to look up programming language specific values for strings that are given in a gtk:builder UI definition file. The primary intended audience is bindings that want to provide deeper integration of the gtk:builder object into the language.

The gtk:builder-scope instance may be used with multiple gtk:builder objects, even at once. By default, GTK will use its own implementation of the gtk:builder-scope instance for the C language.

If you implement the gtk:builder-scope instance for a language binding, you may want to (partially) derive from or fall back to a GtkBuilderCScope, as that class implements support for automatic lookups from C symbols.
Notes:
The Lisp binding implements the gtk:builder-cl-scope subclass. For the Lisp binding, this subclass is the default builder scope for the gtk:builder object.
See also:
2024-10-6
Class gtk:builder-cl-scope
Superclasses:
gtk:builder-scope, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:builder-cl-scope class is the implementation of the gtk:builder-scope interface for the Lisp binding. This class implements the GtkBuilderScope::create_closure() virtual function, which creates Lisp closures for binding signal handlers to objects in the UI definition. An instance of the gtk:builder-cl-scope object is the default builder scope for the gtk:builder object.
See also:
2024-11-3
Class gtk:builder
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
current-object
The current-object property of type g:object (Read / Write)
The object the builder is evaluating for.
scope
The scope property of type GtkBuilderScope (Read / Write / Construct)
The scope the builder is operating in. If the scope property is nil, a gtk:builder-cl-scope instance will be set as the default value.
translation-domain
The translation-domain property of type :string (Read / Write)
The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is nil, the gtk:builder object uses GNU gettext, otherwise GLIB gettext.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:builder object reads XML descriptions of a user interface and instantiates the described objects. To create a gtk:builder object from a user interface description, call the gtk:builder-new-from-file, gtk:builder-new-from-resource or gtk:builder-new-from-string function.

In the (unusual) case that you want to add user interface descriptions from multiple sources to the same gtk:builder object you can call the gtk:builder-new function to get an empty builder and populate it by (multiple) calls to the gtk:builder-add-from-file, gtk:builder-add-from-resource or gtk:builder-add-from-string functions.

The gtk:builder object holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call the gtk:window-destroy function to get rid of them and all the widgets they contain.

The gtk:builder-object and gtk:builder-objects functions can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with the gtk:window-destroy function. Other widgets will either be part of a larger hierarchy constructed by the builder, in which case you should not have to worry about their lifecycle, or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with the g:object-ref function to keep them beyond the lifespan of the builder.

GtkBuilder UI Definitions
The gtk:builder object parses textual descriptions of user interfaces which are specified in XML format. We refer to these descriptions as "GtkBuilder UI definitions" or just "UI definitions" if the context is clear.

Structure of UI definitions
UI definition files are always encoded in UTF-8. The toplevel element is <interface>. It optionally takes a "domain" attribute, which will make the builder look for translated strings using the dgettext() function in the domain specified. This can also be done by calling the gtk:builder-translation-domain function on the builder. For example:
<?xml version="1.0" encoding="UTF-8">
<interface domain="your-app">
  ...
</interface>  


Requirements
The target toolkit version(s) are described by <requires> elements, the "lib" attribute specifies the widget library in question, currently the only supported value is "gtk", and the "version" attribute specifies the target version in the form "<major>.<minor>". The gtk:builder object will error out if the version requirements are not met. For example:
<?xml version="1.0" encoding="UTF-8">
<interface domain="your-app">
  <requires lib="gtk" version="4.0" />
</interface>  


Objects
Objects are defined as children of the <interface> element. Objects are described by <object> elements, which can contain <property> elements to set properties, <signal> elements which connect signals to handlers, and <child> elements, which describe child objects, most often widgets inside a container, but also, for example, actions in an action group, or columns in a tree model. A <child> element contains an <object> element which describes the child object.

Typically, the specific kind of object represented by an <object> element is specified by the "class" attribute. If the type has not been loaded yet, GTK tries to find the type initializer from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the type initializer explicitly with the "type-func" attribute. If your UI definition is referencing internal types, you should make sure to call the g:type-ensure function for each object type before parsing the UI definition.

Objects may be given a name with the "id" attribute, which allows the application to retrieve them from the builder with the gtk:builder-object function. An ID is also necessary to use the object as property value in other parts of the UI definition. GTK reserves IDs starting and ending with "___" (three consecutive underscores) for its own purposes.

Properties
Setting properties of objects is pretty straightforward with the <property> element. The "name" attribute specifies the name of the property, and the content of the element specifies the value. For example:
<object class="GtkButton">
  <property name="label">Hello, world</property>
</object>  
If the "translatable" attribute is set to a true value, GTK uses the gettext() function, or the dgettext() function if the builder has a translation domain set, to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators. For example:
<object class="GtkButton">
  <property name="label"
            translatable="yes"
            context="button">Hello, world</property>
</object>  
The gtk:builder object can parse textual representations for the most common property types:
  • characters
  • strings
  • integers
  • floating-point numbers
  • booleans, strings like "TRUE", "t", "yes", "y", "1" are interpreted as true values, strings like "FALSE", "f", "no", "n", "0" are interpreted as false values
  • enumeration types, can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value
  • flag types, can be specified by their C identifier, short name, integer value, and optionally combined with "|" for bitwise OR, for example, "GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE", or "emoji|lowercase"
  • colors, in a format understood by the gdk:rgba-parse function
  • g:variant parameters, can be specified in the format understood by the g:variant-parse function
  • pixbufs, can be specified as an object ID, a resource path or a filename of an image file to load relative to the builder file or the current working directory if the gtk:builder-add-from-string function was used
  • g:file objects like pixbufs, can be specified as an object ID, a URI or a filename of a file to load relative to the builder file or the current working directory if the gtk:builder-add-from-string function was used
Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed with the gtk:builder-expose-object function. In general, the gtk:builder object allows forward references to objects declared in the local XML. An object does not have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property.

Child objects
Many widgets have properties for child widgets, such as the child property of the gtk:expander widget. In this case, the preferred way to specify the child widget in a UI definition file is to simply set the property:
<object class="GtkExpander">
  <property name="child">
    <object class="GtkLabel">
    ...
    </object>
  </property>
</object>  
Generic containers that can contain an arbitrary number of children, such as the gtk:box widget instead use the <child> element. A <child> element contains an <object> element which describes the child object. Most often, child objects are widgets inside a container, but they can also be, for example, actions in an action group, or columns in a tree model.

Any object type that implements the gtk:buildable interface can specify how children may be added to it. Since many objects and widgets that are included with GTK already implement the gtk:buildable interface, typically child objects can be added using the <child> element without having to be concerned about the underlying implementation.

See the gtk:widget documentation for many examples of using the gtk:builder object with widgets, including setting child objects using the <child> element.

A noteworthy special case to the general rule that only objects implementing the gtk:buildable interface may specify how to handle the <child> element is that the gtk:builder object provides special support for adding objects to a g:list-store object by using the <child> element. For instance:
<object class="GListStore">
  <property name="item-type">MyObject</property>
  <child>
    <object class="MyObject"/>
  </child>
  ...
</object>  
Property bindings
It is also possible to bind a property value to another object’s property value using the "bind-source" attribute to specify the source object of the binding, and optionally, "bind-property" and "bind-flags" attributes to specify the source property and source binding flags respectively. Internally, the gtk:builder class implements this using g:binding objects.

For instance, in the example below the "label" property of the bottom_label widget is bound to the "label" property of the top_button widget:
<object class="GtkBox">
  <property name="orientation">vertical</property>
  <child>
    <object class="GtkButton" id="top_button">
      <property name="label">Hello, world</property>
    </object>
  </child>
  <child>
    <object class="GtkLabel" id="bottom_label">
      <property name="label"
                bind-source="top_button"
                bind-property="label"
                bind-flags="sync-create"/>
    </object>
  </child>
</object>  
For more information, see the documentation of the g:object-bind-property method.

Please note that another way to set up bindings between objects in .ui files is to use the gtk:expression methodology. See the gtk:expression documentation for more information.

Internal children
Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK as part of a composite widget, to set properties on them or to add further children, for example, the content area of a the gtk:dialog widget. This can be achieved by setting the "internal-child" property of the <child> element to a true value. Note that the gtk:builder object still requires an <object> element for the internal child, even if it has already been constructed.

Specialized children
Some widgets have different places where a child can be added, for example, tabs versus page content in notebooks. This can be reflected in a UI definition by specifying the "type" attribute on a <child>. The possible values for the "type" attribute are described in the sections describing the widget-specific portions of UI definitions.

Signal handlers and function pointers
Signal handlers are set up with the <signal> element. The "name" attribute specifies the name of the signal, and the "handler" attribute specifies the function to connect to the signal.
<object class="GtkButton" id="hello_button">
  <signal name="clicked" handler="hello_button__clicked" />
</object>  
The remaining attributes, "after", "swapped" and "object", have the same meaning as the corresponding parameters of the g:signal-connect-object or g:signal-connect-data functions:
  • "after" matches the :after flag, and will ensure that the handler is called after the default class closure for the signal
  • "swapped" matches the :swapped flag, and will swap the instance and closure arguments when invoking the signal handler
  • "object" will bind the signal handler to the lifetime of the object referenced by the attribute
By default "swapped" will be set to "yes" if not specified otherwise, in the case where "object" is set, for convenience. A "last_modification_time" attribute is also allowed, but it does not have a meaning to the builder.

Example UI Definition
<interface>
  <object class="GtkDialog" id=dialog1">
    <child internal-child="content_area">
      <object class="GtkBox">
        <child internal-child="action_area">
          <object class="GtkBox">
            <child>
              <object class="GtkButton" id="ok-button">
                <property name="label" translatable="yes">_Ok</property>
                <property name="use-underline">True</property>
                <signal name="clicked" handler="ok-button-clicked" object="ok-button"/>
              </object>
            </child>
          </object>
        </child>
      </object>
    </child>
  </object>
</interface>  
Using GtkBuildable for extending UI definitions
Objects can implement the gtk:buildable interface to add custom elements and attributes to the XML. Typically, any extension will be documented in each type that implements the interface.

Templates
When describing a gtk:widget object, you can use the <template> tag to describe a UI bound to a specific widget type. GTK will automatically load the UI definition when instantiating the type, and bind children and signal handlers to instance fields and function symbols. For more information, see the gtk:widget documentation.
See also:
2024-11-4
Accessor gtk:builder-current-object (object)
Syntax:
(gtk:builder-current-object object) => current
(setf (gtk:builder-current-object object) current)
Arguments:
object -- a gtk:builder object
current -- a g:object instance
Details:
Accessor of the current-object slot of the gtk:builder class. The gtk:builder-current-object function gets the current object for the builder. The (setf gtk:builder-current-object) function sets the current object. The current object can be thought of the object that the builder is working for and will often be used as the default object when an object is optional.

The gtk:widget-init-template function for example will set the current object to the widget the template is inited for. For functions like the gtk:builder-new-from-resource function, the current object will be nil.
See also:
2024-9-15
Accessor gtk:builder-scope (object)
Syntax:
(gtk:builder-scope object) => scope
(setf (gtk:builder-scope object) scope)
Arguments:
object -- a gtk:builder object
scope -- a gtk:builder-cl-scope object
Details:
Accessor of the scope slot of the gtk:builder class. The gtk:builder-scope function gets the scope in use. The (setf gtk:builder-scope) function sets the scope the builder should operate in. If the scope argument is nil, a gtk:builder-cl-scope instance will be set as the default value.
See also:
2024-11-4
Accessor gtk:builder-translation-domain (object)
Syntax:
(gtk:builder-translation-domain object) => domain
(setf (gtk:builder-translation-domain object) domain)
Arguments:
object -- a gtk:builder object
domain -- a string with the translation domain or nil
Details:
Accessor of the translation-domain slot of the gtk:builder class. The gtk:builder-translation-domain function gets the translation domain of the builder. The (setf gtk:builder-translation-domain) function sets the translation domain.

The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is nil, the gtk:builder object uses the gettext() function, otherwise the d_dgettext() function.
See also:
2024-11-4
Function gtk:builder-new ()
Returns:
The new gtk:builder object.
Details:
Creates a new builder object. This function is only useful if you intend to make multiple calls to the gtk:builder-add-from-file, gtk:builder-add-from-resource or gtk:builder-add-from-string functions in order to merge multiple UI descriptions into a single builder.
See also:
2024-9-15
Function gtk:builder-new-from-file (path)
Arguments:
path -- a pathname or namestring for the file
Returns:
The gtk:builder object containing the described interface.
Details:
Builds the gtk:builder UI definition from an user interface description file. If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program.
See also:
2024-10-6
Function gtk:builder-new-from-resource (path)
Arguments:
path -- a string for the path of the resource file to parse
Returns:
The new gtk:builder object containing the described interface.
Details:
Builds the gtk:builder UI definition from a resource path. If there is an error locating the resource or parsing the description then the program will be aborted.
See also:
2025-3-1
Function gtk:builder-new-from-string (string)
Arguments:
string -- a string with the user interface description
Returns:
The new gtk:builder object containing the interface described by string.
Details:
Builds the user interface described by string in the gtk:builder UI definition format. If there is an error parsing the string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources.
See also:
2024-11-4
Function gtk:builder-add-from-file (builder path)
Arguments:
builder -- a gtk:builder object
path -- a pathname or namestring with the name of the file to parse
Details:
Parses a file containing a gtk:builder UI definition and merges it with the current contents of the builder. This function is useful if you need to call the gtk:builder-current-object function to add user data to callbacks before loading the gtk:builder UI definition. Otherwise, you probably want the gtk:builder-new-from-file function instead.

If there is an error opening the file or parsing the description then the program will be aborted.
See also:
2024-11-21
Function gtk:builder-add-from-resource (builder path)
Arguments:
builder -- a gtk:builder object
path -- a string with the path of the resouce file to parse
Details:
Parses a resource file containing a gtk:builder UI definition and merges it with the current contents of the builder. This function is useful if you need to call the gtk:builder-current-object function to add user data to callbacks before loading the gtk:builder UI definition. Otherwise, you probably want the gtk:builder-new-from-resource function instead.

If there is an error locating the resource or parsing the description then the program will be aborted.
See also:
2024-11-21
Function gtk:builder-add-from-string (builder string)
Arguments:
builder -- a gtk:builder object
string -- a string to parse
Returns:
True on sucess, false if an error occured.
Details:
Parses a string containing a gtk:builder UI definition and merges it with the current contents of the builder. This function is useful if you need to call the gtk:builder-current-object function to add user data to callbacks before loading the gtk:builder UI definition. Otherwise, you probably want the gtk:builder-new-from-string function instead.

If there is an error parsing the string then the program will be aborted.
See also:
2024-10-5
Function gtk:builder-add-objects-from-file (builder path &rest args)
Arguments:
builder -- a gtk:builder object
path -- a pathname or namestring with the name of the file to parse
args -- strings with the object IDs to build
Returns:
The positive value on success, 0 if an error occurred.
Details:
Parses a file containing a gtk:builder UI definition building only the requested objects and merges them with the current contents of builder. Upon errors 0 will be returned.
Notes:
If you are adding an object that depends on an object that is not its child, for instance a gtk:tree-view widget that depends on its gtk:tree-model implementation, you have to explicitely list all of them in args.
See also:
2024-11-21
Function gtk:builder-add-objects-from-resource (builder path &rest args)
Arguments:
builder -- a gtk:builder object
path -- a string with the path of the resource file to parse
args -- strings with the object IDs to build
Returns:
The positive value on success, 0 if an error occurred.
Details:
Parses a resource file containing a gtk:builder UI definition building only the requested objects and merges them with the current contents of builder.
Notes:
If you are adding an object that depends on an object that is not its child, for instance a gtk:tree-view widget that depends on its gtk:tree-model implementation, you have to explicitely list all of them in args.
See also:
2024-11-21
Function gtk:builder-add-objects-from-string (builder string &rest args)
Arguments:
builder -- a gtk:builder object
string -- a string to parse
args -- strings with the object IDs to build
Returns:
The positive value on success, 0 if an error occurred.
Details:
Parses a string containing a gtk:builder UI definition building only the requested objects and merges them with the current contents of builder.
Notes:
If you are adding an object that depends on an object that is not its child, for instance a gtk:tree-view widget that depends on its gtk:tree-model implementation, you have to explicitely list all of them in args.
See also:
2024-11-21
Function gtk:builder-object (builder name)
Arguments:
builder -- a gtk:builder object
name -- a string for the name of the object to get
Returns:
The g:object instance named name or nil if it could not be found in the object tree.
Details:
Gets the object named name from the gtk:builder UI definition.
See also:
2025-1-3
Function gtk:builder-objects (builder)
Arguments:
builder -- a gtk:builder object
Returns:
The list containing all the g:object instances constructed by the gtk:builder object.
Details:
Gets all objects that have been constructed by the builder.
See also:
2024-9-15
Function gtk:builder-expose-object (builder name object)
Arguments:
builder -- a gtk:builder object
name -- a string with the name of the object exposed to the builder
object -- a g:object instance to expose
Details:
Adds an object to the builder object pool so it can be referenced just like any other object built by the builder.
See also:
2024-9-15

Windows

GtkRoot

Interface gtk:root
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:root interface is the interface implemented by all widgets that can act as a toplevel widget to a hierarchy of widgets. The root widget takes care of providing the connection to the windowing system and manages layout, drawing and event delivery for its widget hierarchy. The obvious example of a gtk:root widget is the gtk:window widget.

To get the display to which a gtk:root widget belongs, use the gtk:root-display function. The gtk:root widget also maintains the location of keyboard focus inside its widget hierarchy, with the gtk:root-focus function.
See also:
2024-9-29
Function gtk:root-display (root)
Arguments:
root -- a gtk:root widget
Returns:
The gdk:display object of root.
Details:
Returns the display that the root widget is on.
See also:
2024-9-29
Function gtk:root-focus (root)
Syntax:
(gtk:root-focus root) => widget
(setf (gtk:root-focus root) widget)
Arguments:
root -- a gtk:root widget
widget -- a gtk:widget focus widget, or nil if there is none
Details:
The gtk:root-focus function retrieves the current focused widget within the root widget. Note that this is the widget that would have the focus if the root widget is active. If the root widget is not focused then the gtk:widget-has-focus function will return false for the widget.

If the widget argument is not the current focus widget, and is focusable, the (setf gtk:root-focus) function sets it as the focus widget for the root widget. If the widget argument is nil, unsets the focus widget for the root widget.

To set the focus to a particular widget in the root widget, it is usually more convenient to use the gtk:widget-grab-focus function instead of this function.
See also:
2024-9-29

GtkNative

Interface gtk:native
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:native interface is the interface implemented by all widgets that can provide a gdk:surface object for widgets to render on. The obvious example of a gtk:native widget is the gtk:window widget.

Every widget that is not itself a gtk:native widget is contained in one, and you can get it with the gtk:widget-native function. To get the surface of a gtk:native widget, use the gtk:native-surface function. It is also possible to find the gtk:native widget to which a surface belongs, with the gtk:native-for-surface function.

In addition to a gdk:surface object, a gtk:native widget also provides a gsk:renderer object for rendering on that surface. To get the renderer, use the gtk:native-renderer function.
See also:
2024-9-29
Function gtk:native-for-surface (surface)
Arguments:
surface -- a gdk:surface object
Returns:
The gtk:native widget that is associated with surface.
Details:
Finds the native widget associated with the surface.
See also:
2024-9-29
Function gtk:native-surface (native)
Arguments:
native -- a gtk:native widget
Returns:
The gdk:surface object of native.
Details:
Returns the surface of the native widget.
See also:
2024-9-29
Function gtk:native-renderer (native)
Arguments:
native -- a gtk:native widget
Returns:
The gsk:renderer object of native.
Details:
Returns the renderer that is used for the native widget.
See also:
2024-9-29
Function gtk:native-surface-transform (native)
Syntax:
(gtk:native-surface-transform native) => x, y
Arguments:
native -- a gtk:native widget
Returns:
x -- a double float with the x coordinate
y -- a double float with the y coordinate
Details:
Retrieves the surface transform of the native widget. This is the translation from the surface coordinates into the coordinates of the native widget.
See also:
2024-9-29
Function gtk:native-realize (native)
Arguments:
native -- a gtk:native widget
Details:
Realizes the native widget.
See also:
#2024-9-29
Function gtk:native-unrealize (native)
Arguments:
native -- a gtk:native widget
Details:
Unrealizes the native widget.
See also:
#2024-9-29

GtkWindow

Class gtk:window
Superclasses:
Documented Subclasses:
Direct Slots:
application
The application property of type gtk:application (Read / Write)
The application associated with the window. The application will be kept alive for at least as long as it has any windows associated with it. See the g:application-hold function for a way to keep it alive without windows. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting this property to nil.
child
The child property of type gtk:widget (Read / Write)
The child widget.
decorated
The decorated property of type :boolean (Read / Write)
Whether the window should be decorated by the window manager.
Default value: true
default-height
The default-height property of type :int (Read / Write)
The default height of the window.
Allowed values: >= -1
Default value: 0
default-widget
The default-widget property of type gtk:widget (Read / Write)
The default widget of the window. The default widget is the widget that is activated when the user presses the Enter key.
default-width
The default-width property of type :int (Read / Write)
The default width of the window.
Allowed values: >= -1
Default value: 0
deletable
The deletable property of type :boolean (Read / Write)
Whether the window frame should have a Close button.
Default value: true
destroy-with-parent
The destroy-with-parent property of type :boolean (Read / Write)
Whether this window should be destroyed when the parent is destroyed.
Default value: false
display
The display property of type gdk:display (Read / Write)
The display that will display the window.
focus-visible
The focus-visible property of type :boolean (Read / Write)
Whether "focus rectangles" are currently visible in the window. This property is maintained by GTK based on user input and should not be set by applications.
Default value: true
focus-widget
The focus-widget property of type gtk:widget (Read / Write)
The focus widget. That is the widget that would have the focus if the toplevel window focused.
fullscreened
The fullscreened property of type :boolean (Read / Write)
Whether the window is fullscreen.
Default value: false
handle-menubar-accel
The handle-menubar-accel property of type :boolean (Read / Write)
Whether the window frame should handle the F10 key for activating menubars. Since 4.2
Default value: true
hide-on-close
The hide-on-close property of type :boolean (Read / Write)
Whether the window should be hidden when the users clicks the Close button.
Default value: false
icon-name
The icon-name property of type :string (Read / Write)
Specifies the name of the themed icon to use as the window icon. See the gtk:icon-theme documentation for more details.
Default value: nil
is-active
The is-active property of type :boolean (Read)
Whether the toplevel is the currently active window.
Default value: false
maximized
The maximized property of type :boolean (Read / Write / Construct)
Whether the window is maximized.
Default value: false
mnemonics-visible
The mnemonics-visible property of type :boolean (Read / Write)
Whether mnemonics are currently visible in the window. This property is maintained by GTK based on user input, and should not be set by applications.
Default value: false
modal
The modal property of type :boolean (Read / Write)
If true other windows are not usable while this one is up.
Default value: false
resizable
The resizable property of type :boolean (Read / Write)
If true users can resize the window.
Default value: true
startup-id
The startup-id property of type :string (Write)
The write-only property for setting the startup notification identifier of the window.
Default value: nil
suspended
The suspended property of type :boolean (Read)
Whether the window is suspended.
Default value: false
title
The title property of type :string (Read / Write)
The title of the window.
Default value: nil
titlebar
The titlebar property of type gtk:widget (Read / Write)
The titlebar widget. Since 4.6
transient-for
The transient-for property of type gtk:window (Read / Write / Construct)
The transient parent of the window.
Returned by:
Slot Access Functions:
Details:
The gtk:window widget is a toplevel window which can contain other widgets.

Figure: GtkWindow

Windows normally have decorations that are under the control of the windowing system and allow the user to manipulate the window, for example, to resize it, move it, or close it.
GtkWindow as GtkBuildable:
The gtk:window implementation of the gtk:buildable interface supports setting a child widget as the titlebar by specifying titlebar as the type attribute of a <child> element.
CSS nodes:
window.background [.csd / .solid-csd / .ssd] [.maximized / .fullscreen / .tiled]
├── <child>
╰── <titlebar child>.titlebar [.default-decoration]    
The gtk:window implementation has a main CSS node with name window and .background style class.

Style classes that are typically used with the main CSS node are .csd, when client-side decorations are in use, .solid-csd, for client-side decorations without invisible borders, .ssd, used by mutter when rendering server-side decorations. The gtk:window implementation also represents window states with the following style classes on the main node: .tiled, .maximized, .fullscreen. Specialized types of window often add their own discriminating style classes, such as .popup or .tooltip.

Generally, some CSS properties do not make sense on the toplevel window node, such as margins or padding. When client-side decorations without invisible borders are in use, that is, the .solid-csd style class is added to the main window node, the CSS border of the toplevel window is used for resize drags. In the .csd case, the shadow area outside of the window can be used to resize it.

The gtk:window implementation adds the .titlebar and .default-decoration style classes to the widget that is added as a titlebar child.
Accessibility:
The gtk:window implementation uses the :window role of the gtk:accessible-role enumeration.
Signal Details:
The "activate-default" signal
lambda (window)    :action      
window
The gtk:window widget which received the signal.
The signal is a keybinding signal which gets emitted when the user activates the default widget of the window.
The "activate-focus" signal
lambda (window)    :action      
window
The gtk:window widget which received the signal.
The signal is a keybinding signal which gets emitted when the user activates the currently focused widget of the window.
The "close-request" signal
lambda (window)    :run-last      
window
The gtk:window widget on which the signal is emitted.
Returns
True to stop other handlers from being invoked for the signal.
The signal is emitted when the user clicks on the Close button of the window.
The "enable-debugging" signal
lambda (window toggle)    :action      
window
The gtk:window widget on which the signal is emitted.
toggle
The boolean which toggles the debugger.
Returns
The boolean which is true if the key binding was handled.
The signal is a keybinding signal which gets emitted when the user enables or disables interactive debugging. When the toggle argument is true, interactive debugging is toggled on or off, when it is false, the debugger will be pointed at the widget under the pointer. The default bindings for this signal are the Ctrl-Shift-I and Ctrl-Shift-D keys.
The "keys-changed" signal
lambda (window)    :run-first      
window
The gtk:window widget which received the signal.
The signal gets emitted when the set of accelerators or mnemonics that are associated with the window changes.
Warning: Deprecated since 4.10. Use gtk:shortcut and gtk:event-controller objects to implement keyboard shortcuts.
2024-10-2
Accessor gtk:window-application (object)
Syntax:
(gtk:window-application object) => application
(setf (gtk:window-application object) application)
Arguments:
object -- a gtk:window widget
application -- a gtk:application instance, or nil
Details:
Accessor of the application slot of the gtk:window class. The gtk:window-application function gets the application associated with the window. The (setf gtk:window-application) function sets or unsets the application. The application will be kept alive for at least as long as it has any windows associated with it. See the g:application-hold function for a way to keep it alive without windows.

Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the application property to nil. This is equivalent to calling the gtk:application-remove-window function and/or the gtk:application-add-window function on the old/new applications as relevant.
See also:
2024-10-2
Accessor gtk:window-child (object)
Syntax:
(gtk:window-child object) => child
(setf (gtk:window-child object) child)
Arguments:
object -- a gtk:window widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:window class. The gtk:window-child function gets the child widget of the window. The (setf gtk:window-child) function sets the child widget.
See also:
2024-10-2
Accessor gtk:window-decorated (object)
Syntax:
(gtk:window-decorated object) => setting
(setf (gtk:window-decorated object) setting)
Arguments:
object -- a gtk:window widget
setting -- true to decorate the window
Details:
Accessor of the decorated slot of the gtk:window class. The gtk:window-decorated function returns whether the window has been set to have decorations. The (setf gtk:window-decorated) function sets whether the window should be decorated.

By default, windows are decorated with a title bar, resize controls, etc. Some window managers allow GTK to disable these decorations, creating a borderless window. If you set the decorated property to false using this function, GTK will do its best to convince the window manager not to decorate the window. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling the gtk:widget-visible function.

On Windows, this function always works, since there is no window manager policy involved.
See also:
2024-10-2
Accessor gtk:window-default-height (object)
Syntax:
(gtk:window-default-height object) => height
(setf (gtk:window-default-height object) height)
Arguments:
object -- a gtk:window widget
height -- an integer with the default height
Details:
Accessor of the default-height slot of the gtk:window class. The default height of the window, used when initially showing the window. See the gtk:window-default-size function.
See also:
2024-10-2
Accessor gtk:window-default-widget (object)
Syntax:
(gtk:window-default-widget object) => widget
(setf (gtk:window-default-widget object) widget)
Arguments:
object -- a gtk:window widget
widget -- a gtk:widget object to be the default widget, or nil to unset the default widget for the toplevel
Details:
Accessor of the default-widget slot of the gtk:window class. The gtk:window-default-widget function returns the default widget for the window. The (setf gtk:window-default-widget) function sets or unsets the default widget. The default widget is the widget that is activated when the user presses the Enter key in a dialog for example.
See also:
2024-10-2
Accessor gtk:window-default-width (object)
Syntax:
(gtk:window-default-width object) => width
(setf (gtk:window-default-width object) width)
Arguments:
object -- a gtk:window widget
width -- an integer with the default width
Details:
Accessor of the default-width slot of the gtk:window class. The default width of the window, used when initially showing the window. See the gtk:window-default-size function.
See also:
2024-10-2
Accessor gtk:window-deletable (object)
Syntax:
(gtk:window-deletable object) => setting
(setf (gtk:window-deletable object) setting)
Arguments:
object -- a gtk:window widget
setting -- true to decorate the window as deletable
Details:
Accessor of the deletable slot of the gtk:window class. The gtk:window-deletable function returns whether the window has been set to have a Close button. The (setf gtk:window-deletable) function sets whether the window should be deletable.

By default, windows have a Close button in the window frame. Some window managers allow GTK to disable this button. If you set the deletable property to false using this function, GTK will do its best to convince the window manager not to show a Close button. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling the gtk:widget-visible function.

On Windows, this function always works, since there is no window manager policy involved.
See also:
2024-10-2
Accessor gtk:window-destroy-with-parent (object)
Syntax:
(gtk:window-destroy-with-parent object) => setting
(setf (gtk:window-destroy-with-parent object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether to destroy the window with its transient parent
Details:
Accessor of the destroy-with-parent slot of the gtk:window class. The gtk:window-destroy-with-parent function returns whether the window will be destroyed with its transient parent. The (setf gtk:window-destroy-with-parent) function sets whether to destroy the window with its transient parent. If the setting argument is true, then destroying the transient parent of the window will also destroy the window itself.

This is useful for dialogs that should not persist beyond the lifetime of the main window they are associated with.
See also:
2024-10-2
Accessor gtk:window-display (object)
Syntax:
(gtk:window-display object) => display
(setf (gtk:window-display object) display)
Arguments:
object -- a gtk:window widget
display -- a gdk:display object
Details:
Accessor of the display slot of the gtk:window class. The gtk:window-display function returns the display where the window is displayed. The (setf gtk:window-display) function sets the display. If the window is already mapped, it will be unmapped, and then remapped on the new display.
See also:
2024-10-2
Accessor gtk:window-focus-visible (object)
Syntax:
(gtk:window-focus-visible object) => setting
(setf (gtk:window-focus-visible object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether "focus-rectangles" are currently visible in the window
Details:
Accessor of the focus-visible slot of the gtk:window class. Whether "focus rectangles" are currently visible in the window. This property is maintained by GTK based on user input and should not be set by applications.
See also:
2024-10-2
Accessor gtk:window-focus-widget (object)
Syntax:
(gtk:window-focus-widget object) => widget
(setf (gtk:window-focus-widget object) widget)
Arguments:
object -- a gtk:window widget
widget -- a gtk:widget focus widget
Details:
Accessor of the focus-widget slot of the gtk:window class. The gtk:window-focus-widget function retrieves the current focused widget within the window. The (setf gtk:window-focus-widget) function sets the focus widget.

Note that this is the widget that would have the focus if the toplevel window focused. If the toplevel window is not focused then the gtk:widget-has-focus function will not return true for the widget.

If the widget argument is not the current focus widget, and is focusable, sets it as the focus widget for the window. If the widget argument is nil, unsets the focus widget for the window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use the gtk:widget-grab-focus function instead of this function.
See also:
2024-10-2
Accessor gtk:window-fullscreened (object)
Syntax:
(gtk:window-fullscreened object) => setting
(setf (gtk:window-fullscreened object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether the window is fullscreen
Details:
Accessor of the fullscreened slot of the gtk:window class. The gtk:window-fullscreened function retrieves the current fullscreen state of the window. The (setf gtk:window-fullscreened) function sets the fullscreen state.

Setting this property is the equivalent of calling the gtk:window-fullscreen or gtk:window-unfullscreen functions. Either operation is asynchronous, which means you will need to connect to the "notify" signal in order to know whether the operation was successful.

If the window is not yet mapped, the value returned will show whether the initial requested state is fullscreen.
See also:
2024-10-2
Accessor gtk:window-handle-menubar-accel (object)
Syntax:
(gtk:window-handle-menubar-accel object) => setting
(setf (gtk:window-handle-menubar-accel object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether the window frame should handle the F10 key for activating menubars
Details:
Accessor of the handle-menubar-accel slot of the gtk:window class. The gtk:window-handle-menubar-accel function returns whether the window reacts to the F10 key presses by activating a menubar it contains. The (setf gtk:window-handle-menubar-accel) function sets the property.

Since 4.2
See also:
2024-10-2
Accessor gtk:window-hide-on-close (object)
Syntax:
(gtk:window-hide-on-close object) => setting
(setf (gtk:window-hide-on-close object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether the window should be hidden when the users clicks the Close button
Details:
Accessor of the hide-on-close slot of the gtk:window class. The gtk:window-hide-on-close function returns whether the window will be hidden and not destroyed when the Close button is clicked. The gtk:window-hide-on-close function sets the property.
See also:
2024-10-2
Accessor gtk:window-icon-name (object)
Syntax:
(gtk:window-icon-name object) => name
(setf (gtk:window-icon-name object) name)
Arguments:
object -- a gtk:window widget
name -- a string with the name of the themed icon
Details:
Accessor of the icon-name slot of the gtk:window class. The gtk:window-icon-name function returns the name of the themed icon for the window. The (setf gtk:window-icon-name) function sets the icon for the window from a named themed icon. See the gtk:icon-theme documentation for more details. On some platforms, the window icon is not used at all.

Note that this has nothing to do with the WM_ICON_NAME property which is mentioned in the Inter-Client Communication Conventions Manual (ICCCM).
See also:
2024-10-2
Accessor gtk:window-is-active (object)
Syntax:
(gtk:window-is-active object) => active
(setf (gtk:window-is-active object) active)
Arguments:
object -- a gtk:window widget
active -- a boolean whether the toplevel is the currently active window
Details:
Accessor of the is-active slot of the gtk:window class. The active toplevel is the window receiving keystrokes. The return value is true if the window is active toplevel itself. You might use this function if you wanted to draw a widget differently in an active window from a widget in an inactive window.
See also:
2024-10-2
Accessor gtk:window-maximized (object)
Syntax:
(gtk:window-maximized object) => maximized
(setf (gtk:window-maximized object) maximized)
Arguments:
object -- a gtk:window widget
maximized -- a boolean whether the window is maximized
Details:
Accessor of the maximized slot of the gtk:window class. Setting this property is the equivalent of calling the gtk:window-maximize or gtk:window-unmaximize functions. Either operation is asynchronous, which means you will need to connect to the "notify" signal in order to know whether the operation was successful.
See also:
2024-10-2
Accessor gtk:window-mnemonics-visible (object)
Syntax:
(gtk:window-mnemonics-visible object) => setting
(setf (gtk:window-mnemonics-visible object) setting)
Arguments:
object -- a gtk:window widget
setting -- a boolean whether mnemonics are currently visible in the window
Details:
Accessor of the mnemonics-visible slot of the gtk:window class. Whether mnemonics are currently visible in the window. This property is maintained by GTK based on user input, and should not be set by applications.
See also:
2024-10-2
Accessor gtk:window-modal (object)
Syntax:
(gtk:window-modal object) => modal
(setf (gtk:window-modal object) modal)
Arguments:
object -- a gtk:window widget
modal -- a boolean whether the window is modal
Details:
Accessor of the modal slot of the gtk:window class. The gtk:window-modal function returns true if the window is set to be modal. The (setf gtk:window-modal) function sets a window modal or non-modal.

Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use the gtk:window-transient-for function to make the dialog transient for the parent. Most window managers will then disallow lowering the dialog below the parent.
See also:
2024-10-2
Accessor gtk:window-resizable (object)
Syntax:
(gtk:window-resizable object) => resizable
(setf (gtk:window-resizable object) resizable)
Arguments:
object -- a gtk:window widget
resizable -- true if the user can resize this window
Details:
Accessor of the resizable slot of the gtk:window class. Gets or sets whether the user can resize a window. Windows are user resizable by default.
See also:
2024-10-2
Accessor gtk:window-startup-id (object)
Syntax:
(setf (gtk:window-startup-id object) id)
Arguments:
object -- a gtk:window widget
id -- a string with the startup ID
Details:
Accessor of the startup-id slot of the gtk:window class. The (setf gtk:window-startup-id) function sets a string with the startup notification identifier.

Startup notification identifiers are used by the desktop environment to track application startup, to provide user feedback and other features. This function changes the corresponding property on the underlying gdk:surface object. Normally, startup identifier is managed automatically and you should only use this function in special cases like transferring focus from other processes. You should use this function before calling the gtk:window-present function or any equivalent function generating a window map event.

This function is only useful on X11, not with other GTK targets.
See also:
2024-10-2
Accessor gtk:window-suspended (object)
Syntax:
(gtk:window-suspended object) => suspended
Arguments:
object -- a gtk:window widget
suspended -- a boolean whether the window is suspended
Details:
Accessor of the suspended slot of the gtk:window class. The gtk:window-suspended function retrieves the current suspended state of window. A window being suspended means it is currently not visible to the user, for example by being on an inactive workspace, minimized, or obstructed.

Since 4.12
See also:
2024-10-2
Accessor gtk:window-title (object)
Syntax:
(gtk:window-title object) => title
(setf (gtk:window-title object) title)
Arguments:
object -- a gtk:window widget
title -- a string with the title of the window
Details:
Accessor of the title slot of the gtk:window class. The gtk:window-title function retrieves the title of the window. The (setf gtk:window-title) function sets the title.

The title of a window will be displayed in the title bar. On the X Window System, the title bar is rendered by the window manager, so exactly how the title appears to users may vary according to the exact configuration. The title should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document filename.
See also:
2024-10-2
Accessor gtk:window-titlebar (object)
Syntax:
(gtk:window-titlebar window) => widget
(setf (gtk:window-titlebar window) widget)
Arguments:
window -- a gtk:window widget
widget -- a gtk:widget object to use as titlebar
Details:
Accessor of the titlebar slot of the gtk:window class. The gtk:window-titlebar function returns the custom titlebar for the window. The (setf gtk:window-titlebar) function sets a custom titlebar.

A typical widget used here is the gtk:header-bar widget, as it provides various features expected of a titlebar while allowing the addition of child widgets to it.

If you set a custom titlebar, GTK will do its best to convince the window manager not to put its own titlebar on the window. Depending on the system, this function may not work for a window that is already visible, so you set the titlebar before calling the gtk:widget-visible function.

Since 4.6
See also:
2024-10-2
Accessor gtk:window-transient-for (object)
Syntax:
(gtk:window-transient-for object) => parent
(setf (gtk:window-transient-for object) parent)
Arguments:
object -- a gtk:window widget
parent -- a gtk:window parent window, or nil
Details:
Accessor of the transient-for slot of the gtk:window class. The gtk:window-transient-for function returns the transient parent for the window, or nil if no transient parent has been set. The (setf gtk:window-transient-for) function sets the parent window.

Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to, for example, keep the dialog on top of the main window, or center the dialog over the main window. The gtk:dialog-new-with-buttons function and other convenience functions in GTK will sometimes call the gtk:window-transient-for function on your behalf.

Passing nil for the parent argument unsets the current transient window.

On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X11.
See also:
2024-10-2
Function gtk:window-new ()
Returns:
The new gtk:window widget.
Details:
Creates a new toplevel window, which can contain other widgets. To get an undecorated window, no window borders, use the gtk:window-decorated function. All top-level windows created by the gtk:window-new function are stored in an internal top-level window list. This list can be obtained from the gtk:window-list-toplevels function.

To delete a window, call the gtk:window-destroy function.
See also:
2024-10-2
Function gtk:window-destroy (window)
Arguments:
window -- a gtk:window widget to destroy
Details:
Drop the internal reference GTK holds on toplevel windows.
Examples:
Signal handler for a Cancel button that gets the toplevel window and destroys it to quit the window.
(g:signal-connect cancelbutton "clicked"
                  (lambda (button)
                    (let ((toplevel (gtk:widget-root button)))
                      (gtk:window-destroy toplevel))))    
See also:
2024-10-2
Function gtk:window-default-size (window)
Syntax:
(gtk:window-default-size window) => width, height
(setf (gtk:window-default-size window) (list width height))
Arguments:
window -- a gtk:window widget
width -- an integer with the default width of the window
height -- an integer with the default height of the window
Details:
Accessor of the default size of a gtk:window widget. The gtk:window-default-size function gets the default size of the window. The (setf gtk:window-default-size) function sets the default size. A value of -1 for the width or height indicates that a default size has not been explicitly set for that dimension, so the "natural" size of the window will be used. If the "natural" size of the window, its size request, is larger than the default, the default will be ignored.

Unlike the gtk:widget-size-request function, which sets a size request for a widget and thus would keep users from shrinking the window, this function only sets the initial size, just as if the user had resized the window themselves. Users can still shrink the window again as they normally would. Setting a default size of -1 means to use the "natural" default size, the size request of the window.

The default size of a window only affects the first time a window is shown. If a window is hidden and re-shown, it will remember the size it had prior to hiding, rather than using the default size.

Windows cannot actually be 0 x 0 in size, they must be at least 1 x 1, but passing 0 for width and height is fine, resulting in a 1 x 1 default size.

If you use this function to reestablish a previously saved window size, note that the appropriate size to save is the one returned by the gtk:window-default-size function. Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows.
Examples:
(let ((window (make-instance 'gtk:window)))
  (setf (gtk:window-default-size window) '(300 200))
  (gtk:window-default-size window))
=> 300, 200    
See also:
2024-10-2
Function gtk:window-is-maximized (window)
Arguments:
window -- a gtk:window widget
Returns:
The boolean whether the window is maximized.
Details:
Retrieves the current maximized state of the window. Note that since maximization is ultimately handled by the window manager and happens asynchronously to an application request, you should not assume the return value of this function changing immediately, or at all, as an effect of calling the gtk:window-maximize or gtk:window-unmaximize functions.

If the window is not yet mapped, the value returned will whether the initial requested state is maximized.
See also:
2024-10-2
Function gtk:window-is-fullscreen (window)
Arguments:
window -- a gtk:window widget
Returns:
The boolean whether the window has a fullscreen state.
Details:
Retrieves the current fullscreen state of window. Note that since fullscreening is ultimately handled by the window manager and happens asynchronously to an application request, you should not assume the return value of this function changing immediately, or at all, as an effect of calling the gtk:window-fullscreen or gtk:window-unfullscreen functions.

If the window is not yet mapped, the value returned will whether the initial requested state is fullscreen.
See also:
2024-10-2
Function gtk:window-toplevels ()
Returns:
The g:list-model object with the list of toplevel widgets.
Details:
Returns a list of all existing toplevel windows. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets or add new ones, be aware that the list of toplevels will change and emit the "items-changed" signal.
See also:
2024-10-2
Function gtk:window-list-toplevels ()
Returns:
The list of toplevel gtk:widget objects.
Details:
Returns a list of all existing toplevel windows.
See also:
2024-10-2
Function gtk:window-present (window)
Arguments:
window -- a gtk:window widget
Details:
Presents a window to the user. This may mean raising the window in the stacking order, unminimizing it, moving it to the current desktop and/or giving it the keyboard focus, possibly dependent on the platform of the user, window manager and preferences. If the window is hidden, this function also makes it visible.
See also:
2024-10-2
Function gtk:window-present-with-time (window timestamp)
Arguments:
window -- a gtk:window widget
timestamp -- an unsigned integer with the timestamp of the user interaction, typically a button or key press event, which triggered this call
Details:
Presents a window to the user in response to an user interaction. See the gtk:window-present function for more details.

The timestamp should be gathered when the window was requested to be shown, when clicking a link for example, rather than once the window is ready to be shown.
Warning:
This function is deprecated since 4.14. Use the gtk:window-present funtion.
See also:
2024-10-2
Function gtk:window-close (window)
Arguments:
window -- a gtk:window widget
Details:
Requests that the window is closed. This is similar to what happens when a window manager Close button is clicked. This function can be used with Close buttons in custom titlebars.
See also:
2024-10-2
Function gtk:window-minimize (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to minimize the window. Note that you should not assume the window is definitely minimized afterward, because other entities, for example, the user or window manager, could unminimize it again, or there may not be a window manager in which case minimization is not possible.

It is permitted to call this function before showing a window, in which case the window will be minimized before it ever appears onscreen.

You can track the result of this operation via the state property.
See also:
2024-10-2
Function gtk:window-unminimize (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to unminimize the window. Note that you should not assume the window is definitely unminimized afterward, because the windowing system might not support this functionality. Other entities, for example, the user or the window manager could minimize it again, or there may not be a window manager in which case minimization is not possible.

You can track the result of this operation via the state property.
See also:
2024-10-2
Function gtk:window-maximize (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to maximize the window, so that it becomes full screen. Note that you should not assume the window is definitely maximized afterward, because other entities, for example, the user or window manager could unmaximize it again, and not all window managers support maximization.

It is permitted to call this function before showing a window, in which case the window will be maximized when it appears onscreen initially.

You can track the result of this operation via the state property, or by listening to notifications on the maximized property.
See also:
2024-10-2
Function gtk:window-unmaximize (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to unmaximize the window. Note that you should not assume the window is definitely unmaximized afterward, because other entities, for example, the user or window manager maximize it again, and not all window managers honor requests to unmaximize.

You can track the result of this operation via the state property, or by listening to notifications on the maximized property.
See also:
2024-10-2
Function gtk:window-fullscreen (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to place the window in the fullscreen state. Note that you should not assume the window is definitely full screen afterward, because other entities, for example, the user or window manager, could unfullscreen it again, and not all window managers honor requests to fullscreen windows.

You can track the result of this operation via the state property, or by listening to notifications of the fullscreened property.
See also:
2024-10-2
Function gtk:window-fullscreen-on-monitor (window monitor)
Arguments:
window -- a gtk:window widget
monitor -- a gdk:monitor object to go fullscreen on
Details:
Asks to place the window in the fullscreen state on the given monitor. Note that you should not assume the window is definitely full screen afterward, or that the windowing system allows fullscreen windows on any given monitor.

You can track the result of this operation via the state property, or by listening to notifications of the fullscreened property.
See also:
#2024-10-2
Function gtk:window-unfullscreen (window)
Arguments:
window -- a gtk:window widget
Details:
Asks to toggle off the fullscreen state for the window. Note that you should not assume the window is definitely not full screen afterward, because other entities, for example, the user or window manager, could fullscreen it again, and not all window managers honor requests to unfullscreen windows. But normally the window will end up restored to its normal state. Just do not write code that crashes if not.

You can track the result of this operation via the state property, or by listening to notifications of the fullscreened property.
See also:
2024-10-2
Function gtk:window-default-icon-name ()
Syntax:
(gtk:window-default-icon-name) => name
(setf (gtk:window-default-icon-name) name)
Arguments:
name -- a string with the name of the themed icon
Details:
Accessor of the default icon name of the window. The gtk:window-default-icon-name function returns the fallback icon name for windows. The (setf gtk:window-default-icon-name) function sets an icon to be used as fallback for windows that have not had the gtk:window-icon-name function called on them.
See also:
2024-10-2
Function gtk:window-group (window)
Arguments:
window -- a gtk:window widget, or nil
Returns:
The gtk:window-group object for the window argument or the default window group.
Details:
Returns the window group for the window. If the window has no window group, then the default window group is returned.
See also:
2025-3-30
Function gtk:window-has-group (window)
Arguments:
window -- a gtk:window widget
Returns:
True if the window argument has an explicit window group.
Details:
Returns whether the window has an explicit window group.
See also:
2024-10-12
Function gtk:window-set-auto-startup-notification (setting)
Arguments:
setting -- true to automatically do startup notification
Details:
Call this function to disable the automatic startup notification. By default, after showing the first window, GTK calls the gdk:display-notify-startup-complete function. Call this function to disable the automatic startup notification. You might do this if your first window is a splash screen, and you want to delay notification until after your real main window has been shown, for example.

In that example, you would disable startup notification temporarily, show your splash screen, then re-enable it so that showing the main window would automatically result in notification.
See also:
#2024-10-2
Function gtk:window-set-interactive-debugging (enable)
Arguments:
enable -- true to enable interactice debugging
Details:
Opens or closes the interactive debugger. The debugger offers access to the widget hierarchy of the application and to useful debugging tools.
See also:
2024-10-2
Function gtk:window-is-suspended (window)
Arguments:
window -- a gtk:window widget
Returns:
The boolean whether the window is suspended.
Details:
Retrieves the current suspended state of the window. A window being suspended means it is currently not visible to the user, for example by being on a inactive workspace, minimized, obstructed.

Since 4.12
See also:
2024-10-2

GtkAboutDialog

GEnum gtk:license
Declaration:
(gobject:define-genum "GtkLicense" license
  (:export t
   :type-initializer "gtk_license_get_type")
  (:unknown 0)
  (:custom 1)
  (:gpl-2-0 2)
  (:gpl-3-0 3)
  (:lgpl-2-1 4)
  (:lgpl-3-0 5)
  (:bsd 6)
  (:mit-x11 7)
  (:artistic 8)
  (:gpl-2-0-only 9)
  (:gpl-3-0-only 10)
  (:lgpl-2-1-only 11)
  (:lgpl-3-0-only 12)
  (:agpl-3-0 13)
  (:agpl-3-0-only 14)
  (:bsd-3 15)
  (:apache-2-0 16)
  (:mpl-2-0 17)
  #+gtk-4-14
  (:0bsd 18))  
Values:
:unknown
No license specified.
:custom
A license text is going to be specified by the developer.
:gpl-2-0
The GNU General Public License, version 2.0.
:gpl-3-0
The GNU General Public License, version 3.0.
:lgpl-2-1
The GNU Lesser General Public License, version 2.1.
:lgpl-3-0
The GNU Lesser General Public License, version 3.0.
:bsd
The BSD standard license.
:mit-x11
The MIT/X11 standard license.
:artistic
The Artistic License, version 2.0.
:gpl-2-0-only
The GNU General Public License, version 2.0 only.
:gpl-3-0-only
The GNU General Public License, version 3.0 only.
:lgpl-2-1-only
The GNU Lesser General Public License, version 2.1 only.
:lgpl-3-0-only
The GNU Lesser General Public License, version 3.0 only.
:agpl-3-0
The GNU Affero General Public License, version 3.0 or later.
:agpl-3-0-only
The GNU Affero General Public License, version 3.0 only.
:bsd-3
The 3-clause BSD license.
:apache-2-0
The Apache License, version 2.0.
:mpl-2-0
The Mozilla Public License, version 2.0.
:0bsd
Zero-clause BSD license. Since 4.14
Details:
The type of license for an application.
See also:
2024-5-25
Class gtk:about-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
artists
The artists property of type glib:strv-t (Read / Write)
The people who contributed artwork to the program, as a list of strings. Each string may contain email addresses and URLs, which will be displayed as links.
authors
The authors property of type glib:strv-t (Read / Write)
The authors of the program, as a list of strings. Each string may contain email addresses and URLs, which will be displayed as links.
comments
The comments property of type :string (Read / Write)
Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features.
Default value: nil
copyright
The copyright property of type :string (Read / Write)
Copyright information for the program.
Default value: nil
documenters
The documenters property of type glib:strv-t (Read / Write)
The people documenting the program, as a list of strings. Each string may contain email addresses and URLs, which will be displayed as links.
license
The license property of type :string (Read / Write)
The license of the program. The string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the wrap-license property is set to true. Otherwise the text itself must contain the intended linebreaks. When setting this property to a non-nil value, the license-type property is set to the :custom value of the gtk:license enumeration as a side effect.
Default value: nil
license-type
The license-type property of type gtk:license (Read / Write)
The license of the program, as a value of the gtk:license enumeration. The about dialog will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If the :unknown value is used, the link used will be the same specified in the website property. If the :custom value is used, the current contents of the license property are used. For any other gtk:license value, the contents of the license property are also set by this property as a side effect.
Default value: :unkown
The logo property of type gdk:paintable (Read / Write)
The logo for the about box. If this is not set, the default window icon set with the gtk:window-default-icon-name function will be used.
logo-icon-name
The logo-icon-name property of type :string (Read / Write)
The named icon to use as the logo for the about box. This property overrides the logo property.
Default value: nil
program-name
The program-name property of type :string (Read / Write)
The name of the program. If this is not set, it defaults to the return value of the g:application-name function.
Default value: nil
system-information
The system-information property of type :string (Read / Write)
Information about the system on which the program is running. This information is displayed in a separate page, therefore it is fine to use a long multi-paragraph text. Note that the text should contain the intended linebreaks. The text may contain links in this format "<http://www.some.place/>" and email references in the form "<mail-to@some.body>", and these will be converted into clickable links.
Default value: nil
translator-credits
The translator-credits property of type :string (Read / Write)
Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links.
Default value: nil
version
The version property of type :string (Read / Write)
The version of the program.
Default value: nil
website
The website property of type :string (Read / Write)
The URL for the link to the website of the program. This should be a string starting with "http://".
Default value: nil
website-label
The website-label property of type :string (Read / Write)
The label for the link to the website of the program.
Default value: nil
wrap-license
The wrap-license property of type :boolean (Read / Write)
Whether to wrap the text in the license dialog.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:about-dialog widget offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. The about dialog is typically opened when the user selects the About option from the Help menu. All parts of the about dialog are optional.

Figure: GtkAboutDialog

The about dialog often contain links and email addresses. The about dialog displays these as clickable links. By default, it calls the gtk:file-launcher-launch function when a user clicks one. The behaviour can be overridden with the "activate-link" signal.

To specify a person with an email address, use a string like "Edgar Allan Poe <edgar@poe.com>". To specify a website with a title, use a string like "GTK team https://www.gtk.org".

To make constructing an about dialog as convenient as possible, you can use the gtk:show-about-dialog function which constructs and shows an about dialog and keeps it around so that it can be shown again.

Note that GTK sets a default title of "About %s" on the about dialog window where %s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a gtk:about-dialog widget, as shown in the following example:
(gtk:show-about-dialog nil
                       :program-name "ExampleCode"
                       :logo example-logo
                       :title "About ExampleCode")  
CSS nodes:
The gtk:about-dialog implementation has a single CSS node with the name window and the .aboutdialog style class.
Signal Details:
The "activate-link" signal
lambda (dialog uri)    :run-last      
dialog
The gtk:about-dialog widget on which the signal was emitted.
uri
The string with the URI that is activated.
Returns
True if the link has been activated.
Emitted when a URL is activated. Applications may connect to it to override the default behaviour, which is to call the gtk:file-launcher-launch function.
See also:
2024-11-29
Accessor gtk:about-dialog-artists (object)
Syntax:
(gtk:about-dialog-artists object) => artists
(setf (gtk:about-dialog-artists object) artists)
Arguments:
object -- a gtk:about-dialog widget
artists -- a list of strings with the people who contributed artwork to the program
Details:
Accessor of the artists slot of the gtk:about-dialog class. The gtk:about-dialog-artists function returns the strings which are displayed in the credits page. The (setf gtk:about-dialog-artists) function sets the strings.
See also:
2024-4-11
Accessor gtk:about-dialog-authors (object)
Syntax:
(gtk:about-dialog-authors object) => authors
(setf (gtk:about-dialog-authors object) authors)
Arguments:
object -- a gtk:about-dialog widget
authors -- a list of string with the authors of the program
Details:
Accessor of the authors slot of the gtk:about-dialog class. The gtk:about-dialog-authors function returns the strings which are displayed in the credits page. The (setf gtk:about-dialog-authors) function sets the strings. Each string may contain email addresses and URLs, which will be displayed as links.
Examples:
(setq about (make-instance 'gtk:about-dialog))
=> #<GTK:ABOUT-DIALOG {1009A9FF83}>
(setf (gtk:about-dialog-artists about)
      (list "first author" "second author"))
=> ("first author" "second author")
(gtk:about-dialog-artists about)
=> ("first author" "second author")    
See also:
2024-4-11
Accessor gtk:about-dialog-comments (object)
Syntax:
(gtk:about-dialog-comments object) => comments
(setf (gtk:about-dialog-comments object) comments)
Arguments:
object -- a gtk:about-dialog widget
comments -- a string with comments about the program
Details:
Accessor of the comments slot of the gtk:about-dialog class. The gtk:about-dialog-comments function returns the comments string. The (setf gtk:about-dialog-comments) function sets the comments string to display in the about dialog. The string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features.
See also:
2024-4-11
Syntax:
(gtk:about-dialog-copyright object) => copyright
(setf (gtk:about-dialog-copyright object) copyright)
Arguments:
object -- a gtk:about-dialog widget
copyright -- a string with copyright information
Details:
Accessor of the copyright slot of the gtk:about-dialog class. The gtk:about-dialog-copyright function returns the copyright information for the program. The (setf gtk:about-dialog-copyright) function sets the copyright information. This should be a short string of one or two lines.
See also:
2024-4-11
Accessor gtk:about-dialog-documenters (object)
Syntax:
(gtk:about-dialog-documenters object) => documenters
(setf (gtk:about-dialog-documenters object) documenters)
Arguments:
object -- a gtk:about-dialog widget
documenters -- a string with the people documenting the program
Details:
Accessor of the documenters slot of the gtk:about-dialog class. The gtk:about-dialog-documenters function returns the strings which are displayed in the documenters credits page. The (setf gtk:about-dialog-documenters) function sets the strings. Each string may contain email addresses and URLs, which will be displayed as links.
See also:
2024-4-11
Accessor gtk:about-dialog-license (object)
Syntax:
(gtk:about-dialog-license object) => license
(setf (gtk:about-dialog-license object) license)
Arguments:
object -- a gtk:about-dialog widget
license -- a string with the license of the program
Details:
Accessor of the license slot of the gtk:about-dialog class. The gtk:about-dialog-license function returns the license information. The (setf gtk:about-dialog-license) function sets the license information to be displayed in the secondary license dialog. If the license argument is nil, the license page is hidden.

The text may contain links in this format "<http://www.some.place/>" and email references in the form "<mail-to@some.body>", and these will be converted into clickable links.
See also:
2024-4-11
Accessor gtk:about-dialog-license-type (object)
Syntax:
(gtk:about-dialog-license-type object) => license-type
(setf (gtk:about-dialog-license-type object) license-type)
Arguments:
object -- a gtk:about-dialog widget
license-type -- a value of the gtk:license enumeration
Details:
Accessor of the license-type slot of the gtk:about-dialog class. The gtk:about-dialog-license-type function retrieves the license type of type gtk:license. The (setf gtk:about-dialog-license-type) function sets the license of of the application showing the about dialog from a list of known licenses. This function overrides the license set using the gtk:about-dialog-license function.
See also:
2024-4-11
Syntax:
(gtk:about-dialog-logo object) => logo
(setf (gtk:about-dialog-logo object) logo)
Arguments:
object -- a gtk:about-dialog widget
logo -- a gdk:paintable logo for the about box
Details:
Accessor of the logo slot of the gtk:about-dialog class. The gtk:about-dialog-logo function returns the paintable displayed as logo in the about dialog. The (setf gtk:about-dialog-logo) function sets the paintable. If it is nil, the default window icon set with the gtk:window-default-icon-name function will be used.
See also:
2024-4-11
Accessor gtk:about-dialog-logo-icon-name (object)
Syntax:
(gtk:about-dialog-logo-icon-name object) => name
(setf (gtk:about-dialog-logo-icon-name object) name)
Arguments:
object -- a gtk:about-dialog widget
name -- a string with a namend icon to use as the logo
Details:
Accessor of the logo-icon-name slot of the gtk:about-dialog class. The gtk:about-dialog-logo-icon-name function returns the icon name displayed as logo in the about dialog. The (setf gtk:about-dialog-logo-icon-name) function sets the icon name.
See also:
2024-4-11
Accessor gtk:about-dialog-program-name (object)
Syntax:
(gtk:about-dialog-program-name object) => name
(setf (gtk:about-dialog-program-name object) name)
Arguments:
object -- a gtk:about-dialog widget
name -- a string with the name of the program
Details:
Accessor of the program-name slot of the gtk:about-dialog class. The gtk:about-dialog-program-name function returns the program name displayed in the about dialog. The (setf gtk:about-dialog-program-name) function sets the program name. If this is not set, it defaults to the return value of the g:application-name function.
See also:
2024-4-11
Accessor gtk:about-dialog-translator-credits (object)
Syntax:
(gtk:about-dialog-translator-credits object) => credits
(setf (gtk:about-dialog-translator-credits object) credits)
Arguments:
object -- a gtk:about-dialog widget
credits -- a string with the credits to the translators
Details:
Accessor of the translator-credits slot of the gtk:about-dialog class. The gtk:about-dialog-translator-credits function returns the translator credits string which is displayed in the credits page. The (setf gtk:about-dialog-translator-credits) function sets the translator credits.

The intended use for this string is to display the translator of the language which is currently used in the user interface. Using GNU gettext, a simple way to achieve that is to mark the string for translation:
gtk_about_dialog_set_translator_credits (about, _("translator-credits"));  
It is a good idea to use the customary "translator-credits" msgid for this purpose, since translators will already know the purpose of that msgid, and since the gtk:about-dialog widget will detect if the "translator-credits" property is untranslated and hide the tab.
See also:
2024-4-11
Accessor gtk:about-dialog-version (object)
Syntax:
(gtk:about-dialog-version object) => version
(setf (gtk:about-dialog-version object) version)
Arguments:
object -- a gtk:about-dialog widget
version -- a string with the version of the program
Details:
Accessor of the version slot of the gtk:about-dialog class. The gtk:about-dialog-version function returns the version string. The (setf gtk:about-dialog-version) function sets the version string to display in the about dialog.
See also:
2024-4-11
Accessor gtk:about-dialog-website (object)
Syntax:
(gtk:about-dialog-website object) => website
(setf (gtk:about-dialog-website object) website)
Arguments:
object -- a gtk:about-dialog widget
website -- a string with URL for the link to the website of the program
Details:
Accessor of the website slot of the gtk:about-dialog class. The (setf gtk:about-dialog-website) function returns the website URL. The (setf gtk:about-dialog-website) function sets the URL string starting with "http://" to use for the website link.
See also:
2024-4-11
Accessor gtk:about-dialog-website-label (object)
Syntax:
(gtk:about-dialog-website-label object) => label
(setf (gtk:about-dialog-website-label object) label)
Arguments:
object -- a gtk:about-dialog widget
label -- a string with the label for the link to the website of the program
Details:
Accessor of the website-label slot of the gtk:about-dialog class. The gtk:about-dialog-website-label function returns the URL to use for the website. The (setf gtk:about-dialog-website-label) function sets the URL.
See also:
2024-4-11
Accessor gtk:about-dialog-wrap-license (object)
Syntax:
(gtk:about-dialog-wrap-license object) => setting
(setf (gtk:about-dialog-wrap-license object) setting)
Arguments:
object -- a gtk:about-dialog widget
setting -- a boolean whether to wrap the text in the license dialog
Details:
Accessor of the wrap-license slot of the gtk:about-dialog class. The gtk:about-dialog-wrap-license function returns whether the license text in the about dialog is automatically wrapped. The (setf gtk:about-dialog-wrap-license) function sets the property.
See also:
2024-4-11
Function gtk:about-dialog-new ()
Returns:
The newly created gtk:about-dialog widget.
Details:
Creates a new about dialog.
See also:
2024-4-11
Function gtk:about-dialog-add-credit-section (about section people)
Arguments:
about -- a gtk:about-dialog widget
section -- a string with the name of the section
people -- a list of strings of the people who belong to that section
Details:
Creates a new section in the credits page.
See also:
#2024-4-11
Function gtk:show-about-dialog (parent &rest args)
Arguments:
parent -- a gtk:window transient parent, or nil for none
args -- pairs of property name and property value
Details:
This is a convenience function for showing the about dialog of an application. The constructed about dialog is associated with the parent window and reused for future invocations of this function.
See also:
2024-8-16

GtkAlertDialog

Class gtk:alert-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
buttons
The buttons property of type g:strv-t (Read / Write)
Labels for buttons to show in the alert dialog. The labels should be translated and may contain a "_" to indicate the mnemonic character. If this property is not set, then a Close button is automatically created.
cancel-button
The cancel-button property of type :int (Read / Write)
This property determines what happens when the Escape key is pressed while the alert dialog is shown. If this property holds the index of a button in the buttons property, then pressing the Escape key is treated as if that button was pressed. If it is -1 or not a valid index for the buttons array, then an error is returned. If the buttons property is nil, then the automatically created Close button is treated as both Cancel and Default button, so 0 is returned.
Default value: -1
default-button
The default-button property of type :int (Read / Write)
This property determines what happens when the Return key is pressed while the alert dialog is shown. If this property holds the index of a button in the buttons property, then pressing the Return key is treated as if that button was pressed. If it is -1 or not a valid index for the buttons list, then nothing happens. If the buttons property is nil, then the automatically created Close button is treated as both Cancel and Default button, so 0 is returned.
Default value: -1
detail
The detail property of type :string (Read / Write)
The detail text for the alert dialog.
Default value: nil
message
The message property of type :string (Read / Write)
The message for the alert dialog.
Default value: nil
modal
The modal property of type :boolean (Read / Write)
Whether the alert dialog is modal.
Default value: true
Details:
The gtk:alert-dialog object collects the arguments that are needed to present a message to the user. The message is shown with the gtk:alert-dialog-choose function. This API follows the GIO async pattern, and the result can be obtained by calling the gtk:alert-dialog-choose-finish function.

If you do not need to wait for a button to be clicked, you can use the gtk:alert-dialog-show function.
Examples:
Create an alert dialog with a g:cancellable object.
(defun create-alert-dialog (parent)
  (let ((dialog (make-instance 'gtk:alert-dialog
                               :message "Alert Alert Alert"
                               :detail "The detail of the alert dialog."
                               :buttons '("Cancel" "OK")
                               :cancel-button 0
                               :default-button 1
                               :modal t))
        (cancellable (g:cancellable-new)))
    ;; Cancel the alert dialog after waiting 10 seconds for user response
    (g:timeout-add-seconds 10
                           (lambda ()
                             (g:cancellable-cancel cancellable)
                             glib:+source-remove+))
    ;; Show the alert dialog
    (gtk:alert-dialog-choose dialog
        parent
        cancellable
        ;; The GAsyncReadyCallback function
        (lambda (source result)
          ;; Get the result
          (let ((result (gtk:alert-dialog-choose-finish source result)))
            (format t "Alert dialog result is ~a~%" result))))))    
Since 4.10
See also:
2024-4-11
Accessor gtk:alert-dialog-buttons (object)
Syntax:
(gtk:alert-dialog-buttons object) => buttons
(setf (gtk:alert-dialog-buttons object) buttons)
Arguments:
object -- a gtk:alert-dialog object
buttons -- a list of strings with the button labels
Details:
Accessor of the buttons slot of the gtk:alert-dialog class. The gtk:alert-dialog-buttons function returns the button labels for the alert dialog. The (setf gtk:alert-dialog-buttons) function sets the buttons.

Since 4.10
See also:
2023-9-20
Accessor gtk:alert-dialog-cancel-button (object)
Syntax:
(gtk:alert-dialog-cancel-button object) => button
(setf (gtk:alert-dialog-cancel-button object) button)
Arguments:
object -- a gtk:alert-dialog object
button -- an integer with the new Cancel button
Details:
Accessor of the cancel-button slot of the gtk:alert-dialog class. The gtk:alert-dialog-cancel-button function returns the index of the Cancel button. The (setf gtk:alert-dialog-cancel-button) function sets the index of the Cancel button. See the cancel-button property for details of how this value is used.

Since 4.10
See also:
2023-9-20
Accessor gtk:alert-dialog-default-button (object)
Syntax:
(gtk:alert-dialog-default-button object) => button
(setf (gtk:alert-dialog-default-button object) button)
Arguments:
object -- a gtk:alert-dialog object
button -- an integer with the new Default button
Details:
Accessor of the default-button slot of the gtk:alert-dialog class. The gtk:alert-dialog-default-button function returns the index of the Default button. The (setf gtk:alert-dialog-default-button) function sets the index of the Default button. See the default-button property for details of how this value is used.

Since 4.10
See also:
2023-9-20
Accessor gtk:alert-dialog-detail (object)
Syntax:
(gtk:alert-dialog-detail object) => detail
(setf (gtk:alert-dialog-detail object) detail)
Arguments:
object -- a gtk:alert-dialog object
detail -- a string with the detail text
Details:
Accessor of the detail slot of the gtk:alert-dialog class. The gtk:alert-dialog-detail function returns the detail text that will be shown in the alert dialog. The (setf gtk:alert-dialog-detail) function sets the detail text.

Since 4.10
See also:
2023-9-20
Accessor gtk:alert-dialog-message (object)
Syntax:
(gtk:alert-dialog-message object) => message
(setf (gtk:alert-dialog-message object) message)
Arguments:
object -- a gtk:alert-dialog object
message -- a string with the message
Details:
Accessor of the message slot of the gtk:alert-dialog class. The gtk:alert-dialog-message function returns the message that will be shown in the alert dialog. The (setf gtk:alert-dialog-message) function sets the message.

Since 4.10
See also:
2023-9-20
Function gtk:alert-dialog-new (msg &rest args)
Arguments:
msg -- a format string for the message
args -- arguments for msg
Returns:
The new gtk:alert-dialog object.
Details:
Creates a new alert dialog. The message will be set to the formatted string resulting from the arguments.

Since 4.10
See also:
2024-4-11
Function gtk:alert-dialog-choose (dialog parent cancellable func)
Arguments:
dialog -- a gtk:alert-dialog object
parent -- a parent gtk:window widget
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function shows the alert dialog to the user. The callback will be called when the alert dialog is dismissed. It should call the gtk:alert-dialog-choose-finish function to obtain the result.

It is ok to pass nil for the callback if the alert dialog does not have more than one button. A simpler API for this case is the gtk:alert-dialog-show function.

Since 4.10
See also:
2023-9-20
Function gtk:alert-dialog-choose-finish (dialog result)
Arguments:
dialog -- a gtk:alert-dialog object
result -- a g:async-result object with the result
Returns:
The integer with the index of the button that was clicked, -1 if the alert dialog was cancelled and the cancel-button property is not set.
Details:
Finishes the the gtk:alert-dialog-choose function call and returns the index of the button that was clicked.

Since 4.10
See also:
2024-11-21
Function gtk:alert-dialog-show (dialog parent)
Arguments:
dialog -- a gtk:alert-dialog object
parent -- a parent gtk:window widget
Details:
Show the alert dialog to the user. This function is a simple version of the gtk:alert-dialog-choose function intended for alert dialogs with a single button. If you want to cancel the alert dialog or if the alert dialog has more than one button, you should use that function instead and provide it with a g:cancellable object or callback respectively.

Since 4.10
See also:
2023-9-20

GtkWindowGroup

Class gtk:window-group
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:window-group object restricts the effect of grabs to windows in the same group, thereby making window groups almost behave like separate applications.

A window can be a member in at most one window group at a time. Windows that have not been explicitly assigned to a window group are implicitly treated like windows of the default window group.

Window groups are referenced by each window in the window group. If the windows in the window group are subsequently destroyed, then they will be removed from the window group and drop their references on the window group. When all window have been removed, the window group will be freed.
See also:
2024-4-11
Function gtk:window-group-new ()
Returns:
The new gtk:window-group object.
Details:
Creates a new window group. Modality of windows only affect windows within the same window group.
See also:
2024-4-11
Function gtk:window-group-add-window (group window)
Arguments:
group -- a gtk:window-group object
window -- a gtk:window widget to add
Details:
Adds a window to a window group.
See also:
2024-4-11
Function gtk:window-group-remove-window (group window)
Arguments:
group -- a gtk:window-group object
window -- a gtk:window widget to remove
Details:
Removes a window from a window group.
See also:
2024-4-11
Function gtk:window-group-list-windows (group)
Arguments:
group -- a gtk:window-group object
Returns:
The list of windows inside the window group.
Details:
Returns a list of windows that belong to the window group.
See also:
2024-4-11

GtkNativeDialog

Class gtk:native-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
modal
The modal property of type :boolean (Read / Write)
Whether the window should be modal with respect to its transient parent.
Default value: false
title
The title property of type :string (Read / Write)
The title of the dialog window.
Default value: nil
transient-for
The transient-for property of type gtk:window (Read / Write / Construct)
The transient parent of the dialog, or nil for none.
visible
The visible property of type :boolean (Read / Write)
Whether the window is currently visible.
Default value: false
Slot Access Functions:
Details:
Native dialogs are platform dialogs that do not use the gtk:dialog or gtk:window classes. They are used in order to integrate better with a platform, by looking the same as other native applications and supporting platform specific features.

The gtk:dialog functions cannot be used on such objects, but we need a similar API in order to drive them. The gtk:native-dialog object is an API that allows you to do this. It allows you to set various common properties on the dialog, as well as show and hide it and get a "response" signal when the user finished with the dialog.

Note that unlike the gtk:dialog widget, gtk:native-dialog objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object.
Signal Details:
The "response" signal
lambda (dialog response)    :run-last      
dialog
The gtk:native-dialog object on which the signal is emitted.
response
The integer with the response ID.
Emitted when the user responds to the dialog. When this is called the dialog has been hidden. If you call the gtk:native-dialog-hide function before the user responds to the dialog this signal will not be emitted.
See also:
2025-3-24
Accessor gtk:native-dialog-modal (object)
Syntax:
(gtk:native-dialog-modal object) => modal
(setf (gtk:native-dialog-modal object) modal)
Arguments:
object -- a gtk:native-dialog object
modal -- true if the dialog is modal
Details:
Accessor of the modal slot of the gtk:native-dialog class. The gtk:native-dialog-modal function returns whether the dialog is modal. The (setf gtk:native-dialog-modal) function sets a dialog modal or non-modal.

Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use the gtk:native-dialog-transient-for function to make the dialog transient for the parent. Most window managers will then disallow lowering the dialog below the parent.
See also:
2025-3-24
Accessor gtk:native-dialog-title (object)
Syntax:
(gtk:native-dialog-title object) => title
(setf (gtk:native-dialog-title object) title)
Arguments:
object -- a gtk:native-dialog object
title -- a string for the title of the dialog, or nil if none has been set explicitly
Details:
Accessor of the title slot of the gtk:native-dialog class. The gtk:native-dialog-title function gets the title of the dialog. The (setf gtk:native-dialog-title) function sets the title.
See also:
2025-3-24
Accessor gtk:native-dialog-transient-for (object)
Syntax:
(gtk:native-dialog-transient-for object) => parent
(setf (gtk:native-dialog-transient-for object) parent)
Arguments:
object -- a gtk:native-dialog object
parent -- a gtk:window parent window
Details:
Accessor of the transient-for slot of the gtk:native-dialog class. The gtk:native-dialog-transient-for function fetches the transient parent for the dialog. The (setf gtk:native-dialog-transient-for) function sets the parent.

Dialog windows should be set transient for the main application window they were spawned from. This allows window managers, for example, to keep the dialog on top of the main window, or center the dialog over the main window.

Passing nil for parent unsets the current transient window.
See also:
2025-3-24
Accessor gtk:native-dialog-visible (object)
Syntax:
(gtk:native-dialog-visible object) => visible
(setf (gtk:native-dialog-visible object) visible)
Arguments:
object -- a gtk:native-dialog object
visible -- true if the dialog is visible
Details:
Accessor of the visible slot of the gtk:native-dialog class. Determines whether the dialog is visible.
See also:
2025-3-24
Function gtk:native-dialog-show (dialog)
Arguments:
dialog -- a gtk:native-dialog object
Details:
Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the "response" signal will be emitted. Multiple calls while the dialog is visible will be ignored.
See also:
2025-3-24
Function gtk:native-dialog-hide (dialog)
Arguments:
dialog -- a gtk:native-dialog object
Details:
Hides the dialog if it is visilbe, aborting any interaction. Once this is called the "response" signal will not be emitted until after the next call to the gtk:native-dialog-show function.

If the dialog is not visible this does nothing.
See also:
#2025-3-24
Function gtk:native-dialog-destroy (dialog)
Arguments:
dialog -- a gtk:native-dialog object
Details:
Destroys a dialog. When a dialog is destroyed, it will break any references it holds to other objects. If it is visible it will be hidden and any underlying window system resources will be destroyed.

Note that this does not release any reference to the object, as opposed to destroying a gtk:window widget, because there is no reference from the windowing system to the gtk:native-dialog object.
See also:
2025-3-24

Layout Widgets

GtkBox

Class gtk:box
Superclasses:
Documented Subclasses:
Direct Slots:
baseline-child
The baseline-child property of type :int (Read / Write)
The child widget that determines the baseline, in vertical orientation. Since 4.12
Default value: -1
baseline-position
The baseline-position property of type gtk:baseline-position (Read / Write)
The position of the baseline aligned widgets if extra space is available.
Default value: :center
homogeneous
The homogeneous property of type :boolean (Read / Write)
Whether the children should all be the same size.
Default value: false
spacing
The spacing property of type :int (Read / Write)
The amount of space between children.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:box widget arranges child widgets into a single row or column.

Figure: GtkBox

Whether it is a row or column depends on the value of its orientation property. Within the other dimension, all children are allocated the same size. Of course, the halign and valign properties can be used on the children to influence their allocation.

Use repeated calls to the gtk:box-append function to pack widgets into a box from start to end. Use the gtk:box-remove function to remove widgets from the box. The gtk:box-insert-child-after function can be used to add a child widget at a particular position.

Use the gtk:box-homogeneous function to specify whether or not all children of the box are forced to get the same amount of space and the gtk:box-spacing function to determine how much space will be minimally placed between all children in the box. Note that spacing is added between the children.

Use the gtk:box-reorder-child-after function to move a child widget to a different place in the box.
CSS nodes:
The gtk:box implementation uses a single CSS node with name box.
Accessibility:
Until GTK 4.10, the gtk:box implementation used the :group role of the gtk:accessible-role enumeration. Starting from GTK 4.12, the gtk:box implementation uses the :generic role.
See also:
2023-8-25
Accessor gtk:box-baseline-child (object)
Syntax:
(gtk:box-baseline-child object) => child
(setf (gtk:box-baseline-child object) child)
Arguments:
object -- a gtk:box widget
child -- an integer with the baseline child widget
Details:
Accessor of the baseline-child slot of the gtk:box class. The gtk:box-baseline-child function gets the baseline child widget. The (setf gtk:box-baseline-position) function sets the baseline child widget. This affects only vertical boxes.

Since 4.12
See also:
2024-4-22
Accessor gtk:box-baseline-position (object)
Syntax:
(gtk:box-baseline-position object) => position
(setf (gtk:box-baseline-position object) position)
Arguments:
object -- a gtk:box widget
position -- a value of the gtk:baseline-position enumeration
Details:
Accessor of the baseline-position slot of the gtk:box class. The gtk:box-baseline-position function gets the baseline position of a box. The (setf gtk:box-baseline-position) function sets the baseline position.

This affects only horizontal boxes with at least one baseline aligned child widget. If there is more vertical space available than requested, and the baseline is not allocated by the parent widget then the position value is used to allocate the baseline with respect to the extra space available.
See also:
2024-4-22
Accessor gtk:box-homogeneous (object)
Syntax:
(gtk:box-homogeneous object) => homogeneous
(setf (gtk:box-homogeneous object) homogeneous)
Arguments:
object -- a gtk:box widget
homogeneous -- true to create equal allotments, false for variable allotments
Details:
Accessor of the homogeneous slot of the gtk:box class. The gtk:box-homogeneous function returns whether or not all children of the box are given equal space in the box. The (setf gtk:box-homogeneous) function sets the property.
See also:
2024-4-22
Accessor gtk:box-spacing (object)
Syntax:
(gtk:box-spacing object) => spacing
(setf (gtk:box-spacing object) spacing)
Arguments:
object -- a gtk:box widget
spacing -- an integer with the number of pixels to put between children
Details:
Accessor of the spacing slot of the gtk:box class. The gtk:box-spacing function returns the spacing between children. The (setf gtk:box-spacing) function sets the number of pixels to place between the children of the box.
See also:
2024-4-22
Function gtk:box-new (&optional orientation spacing)
Arguments:
orientation -- an optional gtk:orientation value, the default is :horizontal
spacing -- an optional integer with the number of pixels to place by default between children
Returns:
The new gtk:box widget.
Details:
Creates a new box with the given orientation and an optional value for the spacing property. The default value for the spacing argument is 0.
See also:
2024-10-3
Function gtk:box-append (box child)
Arguments:
box -- a gtk:box widget
child -- a gtk:widget child widget
Details:
Adds a child widget as the last child widget to the box.
See also:
2023-8-25
Function gtk:box-prepend (box child)
Arguments:
box -- a gtk:box widget
child -- a gtk:widget child widget
Details:
Adds a child widget as the first child widget to the box.
See also:
2024-4-11
Function gtk:box-remove (box child)
Arguments:
box -- a gtk:box widget
child -- a gtk:widget child widget
Details:
Removes a child widget from the box. The child widget must have been added before with the gtk:box-append, gtk:box-prepend, or gtk:box-insert-child-after functions.
See also:
2024-4-11
Function gtk:box-insert-child-after (box child sibling)
Arguments:
box -- a gtk:box widget
child -- a gtk:widget child widget
sibling -- a gtk:widget sibling widget after which to insert child
Details:
Inserts the child widget in the position after the sibling widget in the list of children in the box. If the sibling argument is nil, insert the child widget at the first position.
See also:
2024-4-11
Function gtk:box-reorder-child-after (box child sibling)
Arguments:
box -- a gtk:box widget
child -- a gtk:widget child widget to move
sibling -- a gtk:widget sibling widget to move child after
Details:
Moves the child widget to the position after sibling in the list of box children. If the sibling argument is nil, move the child widget to the first position.
See also:
2024-4-11

GtkCenterBox

Class gtk:center-box
Superclasses:
Documented Subclasses:
None
Direct Slots:
baseline-position
The baseline-position property of type gtk:baseline-position (Read / Write)
The position of the baseline aligned widgets if extra space is available.
Default value: :center
center-widget
The center-widget property of type gtk:widget (Read / Write)
The widget that is placed at the center position. Since 4.10
end-widget
The end-widget property of type gtk:widget (Read / Write)
The widget that is placed at the end position. In vertical orientation, the end position is at the bottom. In horizontal orientation, the end position is at the trailing edge with respect to the text direction. Since 4.10
shrink-center-last
The shrink-center-last property of type :boolean (Read / Write)
Whether to shrink the center widget after other children. By default, when there is no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to false, start and end widgets keep natural width and the center widget starts shrinking instead. Since 4.12
Default value: true
start-widget
The start-widget property of type gtk:widget (Read / Write)
The widget that is placed at the start position. In vertical orientation, the start position is at the top. In horizontal orientation, the start position is at the leading edge with respect to the text direction. Since 4.10
Returned by:
Slot Access Functions:
Details:
The gtk:center-box widget arranges three children in a horizontal or vertical arrangement, keeping the middle child centered as well as possible.

Figure: GtkCenterBox

To add children to the gtk:center-box widget, use the gtk:center-box-start-widget, gtk:center-box-center-widget and gtk:center-box-end-widget functions. The sizing and positioning of children can be influenced with the align and expand properties of the children.
GtkCenterBox as GtkBuildable:
The gtk:center-box implementation of the gtk:buildable interface supports placing children in the 3 positions by specifying "start", "center" or "end" as the "type" attribute of a <child> element.
CSS nodes:
The gtk:center-box implementation uses a single CSS node with the name box. The first child of the gtk:center-box widget will be allocated depending on the text direction, that is, in left-to-right layouts it will be allocated on the left and in right-to-left layouts on the right. In vertical orientation, the nodes of the children are arranged from top to bottom.
Accessibility:
Until GTK 4.10, the gtk:center-box implementation used the :group role of the gtk:accessible-role enumeration. Starting from GTK 4.12, the gtk:box implementation uses the :generic role.
See also:
2024-10-1
Accessor gtk:center-box-baseline-position (object)
Syntax:
(gtk:center-box-baseline-position object) => position
(setf (gtk:center-box-baseline-position object) position)
Arguments:
object -- a gtk:center-box widget
position -- a value of the gtk:baseline-position enumeration
Details:
Accessor of the baseline-position slot of the gtk:center-box class. The gtk:center-box-baseline-position function gets the baseline position of a center box. The (setf gtk:center-box-baseline-position) function sets the baseline position.

This affects only horizontal boxes with at least one baseline aligned child widget. If there is more vertical space available than requested, and the baseline is not allocated by the parent widget then the position value is used to allocate the baseline with respect to the extra space available.
See also:
2024-10-1
Accessor gtk:center-box-center-widget (object)
Syntax:
(gtk:center-box-center-widget object) => child
(setf (gtk:center-box-center-widget object) child)
Arguments:
object -- a gtk:center-box widget
child -- a gtk:widget center widget
Details:
Accessor of the center-widget slot of the gtk:center-box class. The gtk:center-box-center-widget function gets the center widget, or nil if there is none. The (setf gtk:center-box-center-widget) function sets the center widget. To remove the existing center widget, pass nil.
See also:
2024-10-1
Accessor gtk:center-box-end-widget (object)
Syntax:
(gtk:center-box-end-widget object) => child
(setf (gtk:center-box-end-widget object) child)
Arguments:
object -- a gtk:center-box widget
child -- a gtk:widget end widget
Details:
Accessor of the end-widget slot of the gtk:center-box class. The gtk:center-box-end-widget function gets the end widget, or nil if there is none. The (setf gtk:center-box-end-widget) function sets the end widget. To remove the existing end widget, pass nil.
See also:
2024-10-1
Accessor gtk:center-box-shrink-center-last (object)
Syntax:
(gtk:center-box-shrink-center-last object) => setting
(setf (gtk:center-box-shrink-center-last object) setting)
Arguments:
object -- a gtk:center-box widget
setting -- a boolean whether to shrink the center widget after other children
Details:
Accessor of the shrink-center-last slot of the gtk:center-box class. The gtk:center-box-shrink-center-last function gets whether the center box shrinks the center widget after other children. The (setf gtk:center-box-shrink-center-last) function sets the property.

By default, when there is no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to false, start and end widgets keep natural width and the center widget starts shrinking instead.

Since 4.12
See also:
2024-10-1
Accessor gtk:center-box-start-widget (object)
Syntax:
(gtk:center-box-start-widget object) => child
(setf (gtk:center-box-start-widget object) child)
Arguments:
object -- a gtk:center-box widget
child -- a gtk:widget start widget
Details:
Accessor of the start-widget slot of the gtk:center-box class. The gtk:center-box-start-widget function gets the start widget, or nil if there is none. The (setf gtk:center-box-start-widget) function sets the start widget. To remove the existing start widget, pass nil.
See also:
2024-10-1
Function gtk:center-box-new ()
Returns:
The new gtk:center-box widget.
Details:
Creates a new gtk:center-box widget.
See also:
2024-10-1

GtkGrid

Class gtk:grid
Superclasses:
Documented Subclasses:
None
Direct Slots:
baseline-row
The baseline-row property of type :int (Read / Write)
The row to align to the baseline when valign has the :center value of the gtk:align enumeration.
Allowed values: >= 0
Default value: 0
column-homogeneous
The column-homogeneous property of type :boolean (Read / Write)
If true, the columns are all the same width.
Default value: false
column-spacing
The column-spacing property of type :int (Read / Write)
The amount of space between two consecutive columns.
Allowed values: [0, 32767]
Default value: 0
row-homogeneous
The row-homogeneous property of type :boolean (Read / Write)
If true, the rows are all the same height.
Default value: false
row-spacing
The row-spacing property of type :int (Read / Write)
The amount of space between two consecutive rows.
Allowed values: [0, 32767]
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:grid widget is a container which arranges its child widgets in rows and columns, with arbitrary positions and horizontal/vertical spans.

Figure: GtkGrid

Children are added using the gtk:grid-attach function. They can span multiple rows or columns. It is also possible to add a child widget next to an existing child widget, using the gtk:grid-attach-next-to function. To remove a child widget from the grid, use the gtk:grid-remove function. The behaviour of the gtk:grid widget when several children occupy the same grid cell is undefined.
GtkGrid as GtkBuildable:
Every child in a gtk:grid widget has access to a custom gtk:buildable element, called <layout>. It can by used to specify a position in the grid and optionally spans. All properties that can be used in the <layout> element are implemented by the gtk:grid-layout-child class.

It is implemented by the gtk:widget class using the gtk:layout-manager class.

To showcase it, here is a simple example:
<object class="GtkGrid" id="my_grid">
  <child>
    <object class="GtkButton" id="button1">
      <property name="label">Button 1</property>
      <layout>
        <property name="column">0</property>
        <property name="row">0</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button2">
      <property name="label">Button 2</property>
      <layout>
        <property name="column">1</property>
        <property name="row">0</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button3">
      <property name="label">Button 3</property>
      <layout>
        <property name="column">2</property>
        <property name="row">0</property>
        <property name="row-span">2</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkButton" id="button4">
      <property name="label">Button 4</property>
      <layout>
        <property name="column">0</property>
        <property name="row">1</property>
        <property name="column-span">2</property>
      </layout>
    </object>
  </child>
</object>    
It organizes the first two buttons side-by-side in one cell each. The third button is in the last column but spans across two rows. This is defined by the row-span property. The last button is located in the second row and spans across two columns, which is defined by the column-span property.
CSS nodes:
The gtk:grid implementation uses a single CSS node with name grid.
Accessibility:
Until GTK 4.10, the gtk:grid implementation used the :group role of the gtk:accessible-role enumeration. Starting from GTK 4.12, the gtk:box implementation uses the :generic role.
See also:
2024-9-14
Accessor gtk:grid-baseline-row (object)
Syntax:
(gtk:grid-baseline-row object) => row
(setf (gtk:grid-baseline-row object) row)
Arguments:
object -- a gtk:grid widget
row -- an integer with the row index
Details:
Accessor of the baseline-row slot of the gtk:grid class. The gtk:grid-baseline-row function returns which row defines the global baseline of the grid. The (setf gtk:grid-baseline-row) function sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the grid.
See also:
2024-9-14
Accessor gtk:grid-column-homogeneous (object)
Syntax:
(gtk:grid-column-homogeneous object) => homogenous
(setf (gtk:grid-column-homogeneous object) homogenous)
Arguments:
object -- a gtk:grid widget
homogeneous -- true to make columns homogeneous
Details:
Accessor of the column-homogeneous slot of the gtk:grid class. The gtk:grid-column-homogeneous function returns whether all columns of the grid have the same width. The (setf gtk:grid-column-homogeneous) function sets whether all columns of the grid will have the same width.
See also:
2024-9-14
Accessor gtk:grid-column-spacing (object)
Syntax:
(gtk:grid-column-spacing object) => spacing
(setf (gtk:grid-column-spacing object) spacing)
Arguments:
object -- a gtk:grid widget
spacing -- an integer with the amount of space to insert between columns
Details:
Accessor of the column-spacing slot of the gtk:grid class. The gtk:grid-column-spacing function returns the amount of space between the columns of the grid. The (setf gtk:grid-column-spacing) function sets the amount of space.
See also:
2024-9-14
Accessor gtk:grid-row-homogeneous (object)
Syntax:
(gtk:grid-row-homogeneous object) => homogeneous
(setf (gtk:grid-row-homogeneous object) homogeneous)
Arguments:
object -- a gtk:grid widget
homogeneous -- true to make rows homogeneous
Details:
Accessor of the row-homogeneous slot of the gtk:grid class. The gtk:grid-row-homogeneous function returns whether all rows of the grid have the same height. The (setf gtk:grid-row-homogeneous) function sets whether all rows of the grid will have the same height.
See also:
2024-9-14
Accessor gtk:grid-row-spacing (object)
Syntax:
(gtk:grid-row-spacing object) => spacing
(setf (gtk:grid-row-spacing object) spacing)
Arguments:
object -- a gtk:grid widget
spacing -- an integer with the amount of space to insert between rows
Details:
Accessor of the row-spacing slot of the gtk:grid class. The gtk:grid-row-spacing function returns the amount of space between the rows of the grid. The (setf gtk:grid-row-spacing) function sets the amount of space.
See also:
2024-9-14
Function gtk:grid-new ()
Returns:
The new gtk:grid widget.
Details:
Creates a new grid widget.
See also:
2024-9-14
Function gtk:grid-attach (grid child left top &optional width height)
Arguments:
grid -- a gtk:grid widget
child -- a gtk:widget child widget to add
left -- an integer with the column number to attach the left side of child to
top -- an integer with the row number to attach the top side of child to
width -- an optional integer with the number of columns that child will span, the default is 1
height -- an optional integer with the number of rows that child will span, the default is 1
Details:
Adds a child widget to the grid. The position of the child widget is determined by the left and top arguments. The number of cells that the child widget will occupy is determined by the optional width and height arguments.
See also:
2024-11-16
Function gtk:grid-attach-next-to (grid child sibling side width height)
Arguments:
grid -- a gtk:grid widget
child -- a gtk:widget child widget to add
sibling -- a gtk:widget sibling widget of the grid that child will be placed next to, or nil to place child at the beginning or end
side -- a gtk:position-type value with the side of sibling that child is positioned next to
width -- an integer with the number of columns that child will span
height -- an integer with the number of rows that child will span
Details:
Adds a child widget to the grid. The child widget is placed next to sibling, on the side determined by side. When the sibling argument is nil, the child widget is placed in row 0, for left or right placement, or column 0, for top or bottom placement, at the end indicated by side.
See also:
2024-9-14
Function gtk:grid-remove (grid child)
Arguments:
grid -- a gtk:grid widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the grid. The child widget must have been added with the gtk:grid-attach or gtk:grid-attach-next-to functions.
See also:
2024-9-14
Function gtk:grid-child-at (grid left top)
Arguments:
grid -- a gtk:grid widget
left -- an integer with the left edge of the cell
top -- an integer with the top edge of the cell
Returns:
The gtk:widget child widget at the given position, or nil.
Details:
Gets the child widget of the grid whose area covers the grid cell whose upper left corner is at left, top.
See also:
2024-9-14
Function gtk:grid-query-child (grid child)
Arguments:
grid -- a gtk:grid widget
child -- a gtk:widget child widget
Returns:
column -- an integer with the column used to attach the left side of child
row -- an integer with the row used to attach the top side of child
width -- an integer with the number of columns child spans
height -- an integer with the number of rows child spans
Details:
Queries the attach points and spans of the child widget inside the given grid.
See also:
2024-9-14
Function gtk:grid-insert-row (grid pos)
Arguments:
grid -- a gtk:grid widget
pos -- an integer with the position to insert the row at
Details:
Inserts a row at the specified position. Children which are attached at or below this position are moved one row down. Children which span across this position are grown to span the new row.
See also:
2024-9-14
Function gtk:grid-insert-column (grid pos)
Arguments:
grid -- a gtk:grid widget
pos -- an integer with the position to insert the column at
Details:
Inserts a column at the specified position. Children which are attached at or to the right of this position are moved one column to the right. Children which span across this position are grown to span the new column.
See also:
2024-9-14
Function gtk:grid-remove-row (grid pos)
Arguments:
grid -- a gtk:grid widget
pos -- an integer with the position of the row to remove
Details:
Removes a row from the grid. Children that are placed in this row are removed, spanning children that overlap this row have their height reduced by one, and children below the row are moved up.
See also:
2024-9-14
Function gtk:grid-remove-column (grid pos)
Arguments:
grid -- a gtk:grid widget
pos -- an integer with the position of the column to remove
Details:
Removes a column from the grid. Children that are placed in this column are removed, spanning children that overlap this column have their width reduced by one, and children after the column are moved to the left.
See also:
2024-9-14
Function gtk:grid-insert-next-to (grid sibling side)
Arguments:
grid -- a gtk:grid widget
sibling -- a gtk:widget sibling widget of the grid that the new row or column will be placed next to
side -- a gtk:position-type value with the side of sibling that child is positioned next to
Details:
Inserts a row or column at the specified position. The new row or column is placed next to sibling, on the side determined by side. If the side argument is :top or :bottom, a row is inserted. If the side argument is :left of :right, a column is inserted.
See also:
2024-9-14
Function gtk:grid-row-baseline-position (grid row)
Syntax:
(gtk:grid-row-baseline-position grid row) => pos
(setf (gtk:grid-row-baseline-position grid row) pos)
Arguments:
grid -- a gtk:grid widget
row -- an integer with a row index
pos -- a value of the gtk:baseline-position enumeration
Details:
The gtk:grid-row-baseline-position function returns the baseline position of row. The (setf gtk:grid-row-baseline-position) function sets how the baseline should be positioned on row of the grid, in case that row is assigned more space than is requested. The default baseline position is :center.
See also:
2024-9-14

GtkRevealer

GEnum gtk:revealer-transition-type
Declaration:
(gobject:define-genum "GtkRevealerTransitionType" revealer-transition-type
  (:export t
   :type-initializer "gtk_revealer_transition_type_get_type")
  (:none 0)
  (:crossfade 1)
  (:slide-right 2)
  (:slide-left 3)
  (:slide-up 4)
  (:slide-down 5)
  (:swing-right 6)
  (:swing-left 7)
  (:swing-up 8)
  (:swing-down 9))  
Values:
:none
No transition
:crossfade
Fade in.
:slide-right
Slide in from the left.
:slide-left
Slide in from the right.
:slide-up
Slide in from the bottom.
:slide-down
Slide in from the top.
:swing-right
Floop in from the left.
:swing-left
Floop in from the right.
:swing-up
Floop in from the bottom.
:swing-down
Floop in from the top.
Details:
These enumeration values describe the possible transitions when the child widget of a gtk:revealer widget is shown or hidden.
See also:
2024-4-12
Class gtk:revealer
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
child-revealed
The child-revealed property of type :boolean (Read)
Whether the child widget is revealed and the animation target reached.
Default value: false
reveal-child
The reveal-child property of type :boolean (Read / Write)
Whether the container should reveal the child widget.
Default value: false
transition-duration
The transition-duration property of type :uint (Read / Write)
The animation duration, in milliseconds.
Default value: 250
transition-type
The transition-type property of type gtk:revealer-transition-type (Read / Write)
The type of animation used to transition.
Default value: :slide-down
Returned by:
Slot Access Functions:
Details:
The gtk:revealer widget is a container which animates the transition of its child widget from invisible to visible. The style of transition can be controlled with a value of the gtk:revealer-transition-type enumeration. These animations respect the gtk-enable-animations setting.
CSS nodes:
The gtk:revealer implementation has a single CSS node with name revealer. When styling the gtk:revealer widget using CSS, remember that it only hides its contents, not itself. That means applied margin, padding and borders will be visible even when the reveal-child property is set to false.
Accessibility:
The gtk:revealer implementation uses the :group role of the gtk:accessible-role enumeration. The child widget of the gtk:revealer widget, if set, is always available in the accessibility tree, regardless of the state of the revealer widget.
See also:
2024-4-15
Accessor gtk:revealer-child (object)
Syntax:
(gtk:revealer-child object) => child
(setf (gtk:revealer-child object) child)
Arguments:
object -- a gtk:revealer widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:revealer class. The gtk:revealer-child function gets the child widget of the revealer. The (setf gtk:revealer-child) function sets the child widget.
See also:
2023-8-8
Accessor gtk:revealer-child-revealed (object)
Syntax:
(gtk:revealer-child-revealed object) => revealed
Arguments:
object -- a gtk:revealer widget
revealed -- a boolean whether the child widget is revealed
Details:
Accessor of the child-revealed slot of the gtk:revealer class. The gtk:revealer-child-revealed function returns whether the child widget is fully revealed, in other words whether the transition to the revealed state is completed.
See also:
2023-8-8
Accessor gtk:revealer-reveal-child (object)
Syntax:
(gtk:revealer-reveal-child object) => reveal
(setf (gtk:revealer-reveal-child object) reveal)
Arguments:
object -- a gtk:revealer widget
reveal -- true to reveal the child widget
Details:
Accessor of the reveal-child slot of the gtk:revealer class. The gtk:revealer-reveal-child function returns whether the child widget is currently revealed. The (setf gtk:revealer-reveal-child) function tells the revealer to reveal or conceal its child widget.

This function returns true as soon as the transition to the revealed state is started. To learn whether the child widget is fully revealed, that is; the transition is completed, use the gtk:revealer-child-revealed function. The transition will be animated with the current transition type of the revealer.
See also:
2024-10-11
Accessor gtk:revealer-transition-duration (object)
Syntax:
(gtk:revealer-transition-duration object) => duration
(setf (gtk:revealer-transition-duration object) duration)
Arguments:
object -- a gtk:revealer widget
duration -- an unsigned integer with the duration, in milliseconds
Details:
Accessor of the transition-duration slot of the gtk:revealer class. The gtk:revealer-transition-duration function returns the amount of time in milliseconds that transitions will take. The (setf gtk:revealer-transition-duration) function sets the duration.
See also:
2023-8-8
Accessor gtk:revealer-transition-type (object)
Syntax:
(gtk:revealer-transition-type object) => setting
(setf (gtk:revealer-transition-type object) setting)
Arguments:
object -- a gtk:revealer widget
setting -- a value of the gtk:revealer-transition-type enumeration
Details:
Accessor of the transition-type slot of the gtk:revealer class. The gtk:revealer-transition-type function gets the type of animation that will be used for transitions in the revealer. The (setf gtk:revealer-transition-duration) function sets the type of animation. Available types include various kinds of fades and slides.
See also:
2023-8-8
Function gtk:revealer-new ()
Returns:
The new gtk:revealer widget.
Details:
Creates a new revealer.
See also:
2023-8-8

GtkListBox

Class gtk:list-box-row
Superclasses:
Documented Subclasses:
None
Direct Slots:
activatable
The activatable property of type :boolean (Read / Write)
Determines whether the "row-activated" signal will be emitted for this row.
Default value: true
child
The child property of type gtk:widget (Read / Write)
The child widget.
selectable
The selectable property of type :boolean (Read / Write)
Determines whether this row can be selected.
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:list-box-row widget is a child widget for the gtk:list-box widget. The gtk:list-box-row widget can be marked as activatable or selectable. If a row is activatable, the "row-activated" signal will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.
Signal Details:
The "activate" signal
lambda (row)    :action      
row
The gtk:list-box-row widget on which the signal is emitted.
This is a keybinding signal, which will cause this row to be activated. If you want to be notified when the user activates a row (by key or not), use the "row-activated" signal on the parent gtk:list-box widget of the row.
See also:
2024-4-13
Accessor gtk:list-box-row-activatable (object)
Syntax:
(gtk:list-box-row-activatable object) => activatable
(setf (gtk:list-box-row-activatable object) activatable)
Arguments:
object -- a gtk:list-box-row widget
activatable -- true to mark the row as activatable
Details:
Accessor of the activatable slot of the gtk:list-box-row class. The gtk:list-box-row-activatable function gets the value of the activatable property for this row. The (setf gtk:list-box-row-activatable) function sets the property.
See also:
2024-4-13
Accessor gtk:list-box-row-child (object)
Syntax:
(gtk:list-box-row-child object) => child
(setf (gtk:list-box-row-child object) child)
Arguments:
object -- a gtk:list-box-row widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:list-box-row class. Gets or sets the child widget of the list box row.
See also:
2024-4-13
Accessor gtk:list-box-row-selectable (object)
Syntax:
(gtk:list-box-row-selectable object) => selectable
(setf (gtk:list-box-row-selectable object) selectable)
Arguments:
object -- a gtk:list-box-row widget
selectable -- true to mark the row as selectable
Details:
Accessor of the selectable slot of the gtk:list-box class. The gtk:list-box-row-selectable function gets the value of the selectable property for this row. The (setf gtk:list-box-row-selectable) function sets the property.
See also:
2024-4-13
Function gtk:list-box-row-new ()
Returns:
The new gtk:list-box-row widget.
Details:
Creates a new list box row, to be used as a child widget of a list box.
See also:
2024-4-13
Function gtk:list-box-row-changed (row)
Arguments:
row -- a gtk:list-box-row widget
Details:
Marks the list box row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers.

Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list box is mirroring some external data set, and *two* rows changed in the external data set then when you call the gtk:list-box-row-changed function on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong.

This generally means that if you do not fully control the data model you have to duplicate the data that affects the list box row functions into the row widgets themselves. Another alternative is to call the gtk:list-box-invalidate-sort function on any model change, but that is more expensive.
See also:
2024-10-11
Function gtk:list-box-row-is-selected (row)
Arguments:
row -- a gtk:list-box-row widget
Returns:
True if row is selected.
Details:
Returns a boolean whether the row is currently selected in its list box.
See also:
2024-10-11
Function gtk:list-box-row-header (row)
Syntax:
(gtk:list-box-row-header row) => header
(setf (gtk:list-box-row-header row) header)
Arguments:
row -- a gtk:list-box-row widget
header -- a gtk:widget object
Details:
The gtk:list-box-row-header function returns the current header of the list box row. This can be used in a gtk:list-box-update-header-func callback function to see if there is a header set already, and if so to update the state of it.

The (setf gtk:list-box-row-header) function sets the current header. This is only allowed to be called from a gtk:list-box-update-header-func callback function. It will replace any existing header in the row, and be shown in front of the row in the list box.
See also:
2024-10-11
Function gtk:list-box-row-index (row)
Arguments:
row -- a gtk:list-box-row widget
Returns:
The integer with the index of the row in the list box, or -1 if the row is not in the list box.
Details:
Gets the current index of the row in its list box.
See also:
#2024-4-15
Class gtk:list-box
Superclasses:
Documented Subclasses:
None
Direct Slots:
accept-unpaired-release
The accept-unpaired-release property of type :boolean (Read / Write)
Accept unpaired release.
Default value: false
activate-on-single-click
The activate-on-single-click property of type :boolean (Read / Write)
Activate row on a single click.
Default value: true
selection-mode
The selection-mode property of type gtk:selection-mode (Read / Write)
The selection mode.
Default value: :single
show-separators
The show-separators property of type :boolean (Read / Write)
Show separators between rows.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:list-box widget is a vertical list box that contains gtk:list-box-row children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Figure: GtkListBox

Using the gtk:list-box widget is often an alternative to the gtk:tree-view widget, especially when the list content has a more complicated layout than what is allowed by a gtk:cell-renderer object, or when the content is interactive, that is, has a button in it.

Although a gtk:list-box widget must have only gtk:list-box-row children you can add any kind of widget to it via the gtk:list-box-prepend, gtk:list-box-append, and gtk:list-box-insert functions, and a gtk:list-box-row widget will automatically be inserted between the list and the widget.

The gtk:list-box-row widget can be marked as activatable or selectable. If a row is activatable, the "row-activated" signal will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.
CSS Nodes:
list
 ╰── row[.activatable]    
The gtk:list-box implementation uses a single CSS node named list. Each gtk:list-box-row widget uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate.
Signal Details:
The "activate-cursor-row" signal
lambda (listbox)    :action      
listbox
The gtk:list-box widget on which the signal is emitted.
The "move-cursor" signal
lambda (listbox step count)    :action      
listbox
The gtk:list-box widget on which the signal is emitted.
step
The value of the gtk:movement-step enumeration.
count
The integer with the number of steps.
The "row-activated" signal
lambda (listbox row)    :run-last      
listbox
The gtk:list-box widget on which the signal is emitted.
row
The activated gtk:list-box-row widget.
The signal is emitted when a row has been activated by the user.
The "row-selected" signal
lambda (listbox row)    :run-last      
listbox
The gtk:list-box widget on which the signal is emitted.
row
The selected gtk:list-box-row widget.
The signal is emitted when a new row is selected, or when the selection is cleared. When the list box is using the :multiple selection mode, this signal will not give you the full picture of selection changes, and you should use the "selected-rows-changed" signal instead.
The "select-all" signal
lambda (listbox)    :action      
listbox
The gtk:list-box widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted to select all children of the list box, if the selection mode permits it. The default bindings for this signal is the Ctrl-a key.
The "selected-rows-changed" signal
lambda (listbox)    :run-first      
listbox
The gtk:list-box widget on which the signal is emitted.
The signal is emitted when the set of selected rows changes.
The "toggle-cursor-row" signal
lambda (listbox)    :action      
listbox
The gtk:list-box widget on which the signal is emitted.
The "unselect-all" signal
lambda (listbox)    :action      
listbox
The gtk:list-box widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted to unselect all children of the list box, if the selection mode permits it. The default bindings for this signal is the Ctrl-Shift-a key.
See also:
2024-4-12
Accessor gtk:list-box-accept-unpaired-release (object)
Syntax:
(gtk:list-box-accept-unpaired-release object) => setting
(setf (gtk:list-box-accept-unpaired-release object) setting)
Arguments:
object -- a gtk:list-box widget
setting -- a boolean whether to accept unpaired release
Details:
Accessor of the accept-unpaired-release slot of the gtk:list-box class.
See also:
2024-4-12
Accessor gtk:list-box-activate-on-single-click (object)
Syntax:
(gtk:list-box-activate-on-single-click object) => setting
(setf (gtk:list-box-activate-on-single-click object) setting)
Arguments:
object -- a gtk:list-box widget
setting -- a boolean whether to activate the row on a single click
Details:
Accessor of the activate-on-single-click slot of the gtk:list-box class. The gtk:list-box-activate-on-single-click function returns whether rows activate on single clicks. The (setf gtk:list-box-activate-on-single-click) function sets whether rows activate on single clicks.

If the setting argument is true, rows will be activated when you click on them, otherwise you need to double-click.
See also:
2024-4-12
Accessor gtk:list-box-selection-mode (object)
Syntax:
(gtk:list-box-selection-mode object) => mode
(setf (gtk:list-box-selection-mode object) mode)
Arguments:
object -- a gtk:list-box widget
mode -- a value of the gtk:selection-mode enumeration
Details:
Accessor of the selection-mode slot of the gtk:list-box class. The gtk:list-box-selection-mode function gets the selection mode of the list box. The (setf gtk:list-box-selection-mode) function sets the selection mode. See the gtk:selection-mode enumeration for details.
See also:
2024-4-12
Accessor gtk:list-box-show-separators (object)
Syntax:
(gtk:list-box-show-separators object) => setting
(setf (gtk:list-box-show-separators object) setting)
Arguments:
object -- a gtk:list-box widget
setting -- a boolean whether to show separators between rows
Details:
Accessor of the show-separators slot of the gtk:list-box class. The gtk:list-box-show-separators function returns whether the list box should show separators between rows. The (setf gtk:list-box-show-separators) function sets whether the list box should show separators.
See also:
2024-4-12
Function gtk:list-box-new ()
Returns:
The new gtk:list-box widget.
Details:
Creates a new list box.
See also:
2024-4-13
Function gtk:list-box-prepend (listbox child)
Arguments:
listbox -- a gtk:list-box widget
child -- a gtk:widget child widget to add
Details:
Prepend a child widget to the list box. If a sort function is set, the child widget will actually be inserted at the calculated position.
See also:
2024-10-11
Function gtk:list-box-append (listbox child)
Arguments:
listbox -- a gtk:list-box widget
child -- a gtk:widget child widget to append
Details:
Append a child widget to the list box. If a sort function is set, the widget will actually be inserted at the calculated position.
See also:
2024-10-11
Function gtk:list-box-insert (listbox child position)
Arguments:
listbox -- a gtk:list-box widget
child -- a gtk:widget child widget to add
position -- an integer with the position to insert the child widget in
Details:
Insert the child widget into the list box at the given position. If a sort function is set, the child widget will actually be inserted at the calculated position.

If the position is -1, or larger than the total number of items in the list box, then the child widget will be appended to the end.
See also:
2024-10-11
Function gtk:list-box-remove (listbox child)
Arguments:
listbox -- a gtk:list-box widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the list box.
See also:
2024-10-11
Function gtk:list-box-remove-all (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Removes all child widgets from the list box.

Since 4.12
See also:
2024-10-11
Function gtk:list-box-select-row (listbox row)
Arguments:
listbox -- a gtk:list-box widget
row -- a gtk:list-box-row widget
Details:
Make the list box row the currently selected row.
See also:
2024-10-11
Function gtk:list-box-unselect-row (listbox row)
Arguments:
listbox -- a gtk:list-box widget
row -- a gtk:list-box-row widget
Details:
Unselects a single row of the list box, if the selection mode allows it. See the gtk:list-box-selection-mode function and the gtk:selection-mode enumeration for more information about selection modes of the list box.
See also:
2024-10-11
Function gtk:list-box-select-all (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Select all children of the list box, if the selection mode allows it. See the gtk:list-box-selection-mode function and the gtk:selection-mode enumeration for more information about selection modes of the list box.
See also:
2024-10-11
Function gtk:list-box-unselect-all (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Unselect all children of the list box, if the selection mode allows it. See the gtk:list-box-selection-mode function and the gtk:selection-mode enumeration for more information about selection modes of the list box.
See also:
2024-10-11
Function gtk:list-box-selected-row (listbox)
Arguments:
listbox -- a gtk:list-box widget
Returns:
The selected gtk:list-box-row widget.
Details:
Gets the selected row. Note that the list box may allow multiple selection, in which case you should use the gtk:list-box-selected-foreach function to find all selected rows.
See also:
2024-10-11
Function gtk:list-box-selected-rows (listbox)
Arguments:
listbox -- a gtk:list-box widget
Returns:
The list containing the gtk:list-box-row widget for each selected row.
Details:
Creates a list of all selected rows in the list box.
See also:
2024-10-11
Function gtk:list-box-adjustment (listbox)
Syntax:
(gtk:list-box-adjustment listbox) => adjustment
(setf (gtk:list-box-adjustment listbox) adjustment)
Arguments:
listbox -- a gtk:list-box widget
adjustment -- a gtk:adjustment object
Details:
The gtk:list-box-adjustment function gets the adjustment (if any) that the list box uses for vertical scrolling. The (setf gtk:list-box-adjustment) function sets the adjustment.

For instance, this is used to get the page size for PageUp/Down key handling. In the normal case when the list box is packed inside a gtk:scrolled-window widget the adjustment from that will be picked up automatically, so there is no need to manually do that.
See also:
2024-10-11
Function gtk:list-box-set-placeholder (listbox placeholder)
Arguments:
listbox -- a gtk:list-box widget
placeholder -- a gtk:widget object
Details:
Sets the placeholder that is shown in the list box when it does not display any visible children.
See also:
2024-10-11
Function gtk:list-box-row-at-index (listbox index)
Arguments:
listbox -- a gtk:list-box widget
index -- an integer with the index of the row
Returns:
The gtk:list-box-row widget at index.
Details:
Gets the n-th child in the list box (not counting headers). If the index argument is negative or larger than the number of items in the list box, nil is returned.
See also:
2024-10-11
Function gtk:list-box-row-at-y (listbox y)
Arguments:
listbox -- a gtk:list-box widget
y -- an integer with the position of the row
Returns:
The gtk:list-box-row widget for the given y coordinate.
Details:
Gets the row at the y position in the list box.
See also:
#2024-4-13
Callback gtk:list-box-foreach-func
Syntax:
lambda (listbox row)
Arguments:
listbox -- a gtk:list-box widget
row -- a gtk:list-box-row widget
Details:
A callback function used by the gtk:list-box-selected-foreach function. It will be called on every selected child widget of the list box.
See also:
2024-10-11
Function gtk:list-box-selected-foreach (listbox func)
Arguments:
listbox -- a gtk:list-box widget
func -- a gtk:list-box-foreach-func callback function
Details:
Calls a function for each selected child. Note that the selection cannot be modified from within this function.
See also:
2024-10-11
Callback gtk:list-box-filter-func
Syntax:
lambda (row) => result
Arguments:
row -- a gtk:list-box-row widget that may be filtered
result -- true if the row should be visible, false otherwise
Details:
Will be called whenever the row changes or is added and lets you control if the row should be visible or not.
See also:
#2024-4-13
Function gtk:list-box-set-filter-func (listbox func)
Arguments:
listbox -- a gtk:list-box widget
func -- a gtk:list-box-filter-func callback function that lets you filter which rows to show
Details:
By setting a filter function on the list box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows.

The func callback function will be called for each row after the call, and it will continue to be called each time a row changes via the gtk:list-box-row-changed function, or when the gtk:list-box-invalidate-filter function is called.

Note that using a filter function is incompatible with using a model, see the gtk:list-box-bind-model function.
See also:
#2024-4-13
Function gtk:list-box-invalidate-filter (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Update the filtering for all rows. Call this when the result of the filter function on the list box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the search entry with the search string has changed.
See also:
#2024-4-13
Callback gtk:list-box-update-header-func
Syntax:
lambda (row before)
Arguments:
row -- a gtk:list-box-row widget with the row to update
before -- a gtk:list-box-row widget before row, or nil if it is the first row
Details:
Whenever row changes or which row is before row changes this is called, which lets you update the header on row. You may remove or set a new one via the gtk:list-box-set-header-func function or just change the state of the current header widget.
See also:
#2024-4-13
Function gtk:list-box-set-header-func (listbox func)
Arguments:
listbox -- a gtk:list-box widget
func -- a gtk:list-box-update-header-func callback function that lets you add row headers
Details:
By setting a header function on the list box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list box. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind.

The func callback function can look at the current header widget using the gtk:list-box-row-header function and either update the state of the widget as needed, or set a new one using the (setf gtk:list-box-row-header) function. If no header is needed, set the header to nil.

Note that you may get many calls of the func callback function to this for a particular row when, for example, changing things that do not affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one.

The func callback function will be called for each row after the call, and it will continue to be called each time a row changes via the gtk:list-box-row-changed function, and when the row before changes either by the gtk:list-box-row-changed function on the previous row, or when the previous row becomes a different row. It is also called for all rows when the gtk:list-box-invalidate-headers function is called.
See also:
#2024-4-13
Function gtk:list-box-invalidate-headers (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Update the separators for all rows. Call this when the result of the header function on the list box is changed due to an external factor.
See also:
#2024-4-13
Callback gtk:list-box-sort-func
Syntax:
lambda (row1 row2) => result
Arguments:
row1 -- a gtk:list-box-row widget with the first row
row2 -- a gtk:list-box-row widget with the second row
result -- an integer which is < 0 if row1 should be before row2, 0 if they are equal and > 0 otherwise
Details:
The type of the callback function that compares two rows to determine which should be first.
See also:
#2024-4-13
Function gtk:list-box-set-sort-func (listbox func)
Arguments:
listbox -- a gtk:list-box widget
func -- a gtk:list-box-sort-func callback function for the sort function
Details:
By setting a sort function on the list box one can dynamically reorder the rows of the list, based on the contents of the rows.

The func callback function will be called for each row after the call, and will continue to be called each time a row changes via the gtk:list-box-row-changed function, and when the gtk:list-box-invalidate-sort function is called.

Note that using a sort function is incompatible with using a model. See the gtk:list-box-bind-model function.
See also:
#2024-4-13
Function gtk:list-box-invalidate-sort (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
Update the sorting for all rows. Call this when the result of the sort function on the list box is changed due to an external factor.
See also:
#2024-4-13
Function gtk:list-box-drag-highlight-row (listbox row)
Arguments:
listbox -- a gtk:list-box widget
row -- a gtk:list-box-row widget
Details:
Add a drag highlight to a row. This is a helper function for implementing DnD onto a gtk:list-box widget. The passed in row will be highlighted by setting the :drop-active state from the gtk:state-flags flags and any previously highlighted row will be unhighlighted.

The row will also be unhighlighted when the widget gets a drag leave event.
See also:
#2024-4-13
Function gtk:list-box-drag-unhighlight-row (listbox)
Arguments:
listbox -- a gtk:list-box widget
Details:
If a row has previously been highlighted via the gtk:list-box-drag-highlight-row function it will have the highlight removed.
See also:
#2024-4-13
Callback gtk:list-box-create-widget-func
Syntax:
lambda (object) => result
Arguments:
object -- a g:object instance for the item from the model for which to create a widget for
result -- a gtk:widget object that represents item
Details:
Called for list boxes that are bound to a g:list-model object with the gtk:list-box-bind-model function for each item that gets added to the model. If the widget returned is not a gtk:list-box-row widget, then the widget will be inserted as the child of an intermediate gtk:list-box-row widget.
See also:
#2024-4-15
Function gtk:list-box-bind-model (listbox model func)
Arguments:
listbox -- a gtk:list-box widget
model -- a g:list-model object to be bound to listbox
func -- a gtk:list-box-create-widget-func callback function that creates widgets for items or nil in case you also passed nil as model
Details:
Binds a model to the list box. If the list box was already bound to a model, that previous binding is destroyed.

The contents of the list box are cleared and then filled with widgets that represent items from the model. The list box is updated whenever the model changes. If the model argument is nil, the list box is left empty.

It is undefined to add or remove widgets directly, for example, with the gtk:list-box-insert function, while the list box is bound to a model.

Note that using a model is incompatible with the filtering and sorting functionality in the list box. When using a model, filtering and sorting should be implemented by the model.
See also:
#2024-4-13

GtkFlowBox

Class gtk:flow-box-child
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
Returned by:
Slot Access Functions:
Details:
The gtk:flow-box-child widget is the kind of widget that can be added to a gtk:flow-box widget.
Accessibility:
The gtk:flow-box-child implementation uses the :grid-cell role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (child)    :action      
child
The gtk:flow-box-child widget on which the signal is emitted.
The signal is emitted when the user activates a child widget in a gtk:flow-box widget, either by clicking or double-clicking, or by using the Space or Enter key. While this signal is used as a keybinding signal, it can be used by applications for their own purposes.
See also:
2024-4-15
Accessor gtk:flow-box-child-child (object)
Syntax:
(gtk:flow-box-child-child object) => child
(setf (gtk:flow-box-child-child object) child)
Arguments:
object -- a gtk:flow-box-child widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:flow-box-child class. The gtk:flow-box-child-child function gets the child widget of the flow box child. The (setf gtk:flow-box-child-child) function sets the child widget.
See also:
2024-4-14
Function gtk:flow-box-child-new ()
Returns:
The new gtk:flow-box-child widget.
Details:
Creates a new gtk:flow-box-child widget, to be used as a child widget of a gtk:flow-box widget.
See also:
2024-4-14
Function gtk:flow-box-child-index (child)
Arguments:
child -- a gtk:flow-box-child widget
Returns:
The integer with the index of the child, or -1 if the child is not in a flow box.
Details:
Gets the current index of the child widget in its flow box.
See also:
2024-6-29
Function gtk:flow-box-child-is-selected (child)
Arguments:
child -- a gtk:flow-box-child widget
Returns:
True if child is selected.
Details:
Returns whether the child widget is currently selected in its flow box.
See also:
2024-6-29
Function gtk:flow-box-child-changed (child)
Arguments:
child -- a gtk:flow-box-child widget
Details:
Marks the child widget as changed, causing any state that depends on this to be updated. This affects sorting and filtering.

Note that calls to this method must be in sync with the data used for the sorting and filtering functions. For instance, if the list is mirroring some external data set, and *two* children changed in the external data set when you call the gtk:flow-box-child-changed function on the first child widget, the sort function must only read the new data for the first of the two changed children, otherwise the resorting of the children will be wrong.

This generally means that if you do not fully control the data model, you have to duplicate the data that affects the sorting and filtering functions into the widgets themselves. Another alternative is to call the gtk:flow-box-invalidate-sort function on any model change, but that is more expensive.
See also:
#2024-4-14
Class gtk:flow-box
Superclasses:
Documented Subclasses:
None
Direct Slots:
accept-unpaired-release
The accept-unpaired-release property of type :boolean (Read / Write)
Accept an unpaired release event.
Default value: false
activate-on-single-click
The activate-on-single-click property of type :boolean (Read / Write)
Determines whether children can be activated with a single click, or require a double click.
Default value: true
column-spacing
The column-spacing property of type :uint (Read / Write)
The amount of horizontal space between two children.
Default value: 0
homogeneous
The homogeneous property of type :boolean (Read / Write)
Determines whether all children should be allocated the same size.
Default value: false
max-children-per-line
The max-children-per-line property of type :uint (Read / Write)
The maximum amount of children to request space for consecutively in the given orientation.
Default value: 7
min-children-per-line
The min-children-per-line property of type :uint (Read / Write)
The minimum number of children to allocate consecutively in the given orientation. Setting the minimum children per line ensures that a reasonably small height will be requested for the overall minimum width of the box.
Default value: 0
row-spacing
The row-spacing property of type :uint (Read / Write)
The amount of vertical space between two children.
Default value: 0
selection-mode
The selection-mode property of type gtk:selection-mode (Read / Write)
The selection mode used by the flow box.
Default value: :single
Returned by:
Slot Access Functions:
Details:
The gtk:flow-box widget positions child widgets in sequence according to its orientation.

Figure: GtkFlowBox

For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested.

Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested.

The size request of a gtk:flow-box widget alone may not be what you expect. If you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a gtk:scrolled-window widget to enable that.

The children of a gtk:flow-box widget can be dynamically sorted and filtered.

Although a gtk:flow-box widget must have only gtk:flow-box-child child widgets, you can add any kind of widget to it via the gtk:flow-box-insert function, and a gtk:flow-box-child widget will automatically be inserted between the flow box and the widget.
CSS nodes:
flowbox
├── flowboxchild
│   ╰── <child>
├── flowboxchild
│   ╰── <child>
│
╰── [rubberband]    
The gtk:flow-box implementation uses a single CSS node with name flowbox. The gtk:flow-box-child implementation uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used.
Accessibility:
The gtk:flow-box implementation uses the :grid role of the gtk:accessible-role enumeration.
Signal Details:
The "activate-cursor-child" signal
lambda (flowbox)    :action      
flowbox
The gtk:flow-box widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted when the user activates the flow box.
The "child-activated" signal
lambda (flowbox child)    :run-last      
flowbox
The gtk:flow-box widget on which the signal is emitted.
child
The gtk:flow-box-child widget that is activated.
The signal is emitted when a child has been activated by the user.
The "move-cursor" signal
lambda (flowbox step count)    :action      
flowbox
The gtk:flow-box widget on which the signal is emitted.
step
The granularity to the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
Returns
True to stop other handlers from being invoked for the event. False to propagate the event further.
The signal is a keybinding signal which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically.

The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. Arrow keys move by individual children. Home/End keys move to the ends of the box. PageUp/PageDown keys move vertically by pages.
The "select-all" signal
lambda (flowbox)    :action      
flowbox
The gtk:flow-box widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted to select all children of the box, if the selection mode permits it. The default bindings for this signal is the Ctrl-a key.
The "selected-children-changed" signal
lambda (flowbox)    :run-first      
box
The gtk:flow-box on which the signal is emitted.
The signal is emitted when the set of selected children changes. Use the gtk:flow-box-selected-foreach or gtk:flow-box-selected-children functions to obtain the selected children.
The "toggle-cursor-child" signal
lambda (flowbox)    :action      
flowbox
The gtk:flow-box widget on which the signal is emitted.
The signal is a keybinding signal which toggles the selection of the child that has the focus. The default binding for this signal is the Ctrl-Space key.
The "unselect-all" signal
lambda (flowbox)    :action      
flowbox
The gtk:flow-box widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted to unselect all children of the box, if the selection mode permits it. The default bindings for this signal is the Ctrl-Shift-a key.
See also:
2024-4-14
Accessor gtk:flow-box-accept-unpaired-release (object)
Syntax:
(gtk:flow-box-accept-unpaired-release object) => setting
(setf (gtk:flow-box-accept-unpaired-release object) setting)
Arguments:
object -- a gtk:flow-box widget
setting -- a boolean whether to accept an unpaired release event
Details:
Accessor of the accept-unpaired-release slot of the gtk:flow-box class.
See also:
2024-4-14
Accessor gtk:flow-box-activate-on-single-click (object)
Syntax:
(gtk:flow-box-activate-on-single-click object) => setting
(setf (gtk:flow-box-activate-on-single-click object) setting)
Arguments:
object -- a gtk:flow-box widget
setting -- false to emit the "child-activated" signal on a single click
Details:
Accessor of the activate-on-single-click slot of the gtk:flow-box class. The gtk:flow-box-activate-on-single-click function returns whether children activate on single clicks. If the setting argument is true, children will be activated when you click on them, otherwise you need to double click.
See also:
2024-4-14
Accessor gtk:flow-box-column-spacing (object)
Syntax:
(gtk:flow-box-column-spacing object) => spacing
(setf (gtk:flow-box-column-spacing object) spacing)
Arguments:
object -- a gtk:flow-box widget
spacing -- an unsigned integer with the spacing to use.
Details:
Accessor of the column-spacing slot of the gtk:flow-box class. The gtk:flow-box-column-spacing function gets the horizontal space to add between children. The (setf gtk:flow-box-column-spacing) function sets the horizontal spacing.
See also:
2024-4-14
Accessor gtk:flow-box-homogeneous (object)
Syntax:
(gtk:flow-box-homogeneous object) => homogeneous
(setf (gtk:flow-box-homogeneous object) homogeneous)
Arguments:
object -- a gtk:flow-box widget
homogeneous -- true to create equal allotments, false for variable allotments
Details:
Accessor of the homogeneous slot of the gtk:flow-box class. The gtk:flow-box-homogeneous function returns whether the flow box is homogeneous - all children are the same size. The (setf gtk:flow-box-homogeneous) function sets the property.
See also:
2024-4-14
Accessor gtk:flow-box-max-children-per-line (object)
Syntax:
(gtk:flow-box-max-children-per-line object) => n-children
(setf (gtk:flow-box-max-children-per-line object) n-children)
Arguments:
object -- a gtk:flow-box widget
n-children -- an unsigned integer with the maximum number of children per line
Details:
Accessor of the max-children-per-line slot of the gtk:flow-box class. The gtk:flow-box-max-children-per-line function gets the maximum number of children per line to request and allocate space for in the orientation of the flow box. The (setf gtk:flow-box-max-children-per-line) function sets the maximum number of children.

Setting the maximum number of children per line limits the overall natural size request to be no more than n-children children long in the given orientation.
See also:
2024-4-14
Accessor gtk:flow-box-min-children-per-line (object)
Syntax:
(gtk:flow-box-min-children-per-line object) => n-children
(setf (gtk:flow-box-min-children-per-line object) n-children)
Arguments:
object -- a gtk:flow-box widget
n-children -- an unsigned integer with the minimum number of children per line
Details:
Accessor of the min-children-per-line slot of the gtk:flow-box class. The gtk:flow-box-min-children-per-line gets the minimum number of children per line in the orientation of the flow box before flowing. The (setf gtk:flow-box-min-children-per-line) function sets the minimum number of children per line.
See also:
2024-4-14
Accessor gtk:flow-box-row-spacing (object)
Syntax:
(gtk:flow-box-row-spacing object) => spacing
(setf (gtk:flow-box-row-spacing object) spacing)
Arguments:
object -- a gtk:flow-box widget
spacing -- an unsigned integer with the spacing to use
Details:
Accessor of the row-spacing slot of the gtk:flow-box class. The gtk:flow-box-row-spacing function gets the vertical space to add between children. The (setf gtk:flow-box-row-spacing) function sets the vertical spacing.
See also:
2024-4-14
Accessor gtk:flow-box-selection-mode (object)
Syntax:
(gtk:flow-box-selection-mode object) => mode
(setf (gtk:flow-box-selection-mode object) mode)
Arguments:
object -- a gtk:flow-box widget
mode -- a value of the gtk:selection-mode enumeration
Details:
Accessor of the selection-mode slot of the gtk:flow-box class. The gtk:flow-box-selection-mode function gets the selection mode of the flow box. The (setf gtk:flow-box-selection-mode) function sets how selection works in the flow box.
See also:
2024-4-14
Function gtk:flow-box-new ()
Returns:
The new gtk:flow-box widget.
Details:
Creates a new flow box.
See also:
2024-4-14
Function gtk:flow-box-insert (flowbox child position)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget to add
position -- an integer with the position to insert the child widget in
Details:
Inserts the child widget into the flow box at a given position. If a sort function is set, the widget will actually be inserted at the calculated position.

If the position argument is -1, or larger than the total number of children in the flow box, then the child widget will be appended to the end.
See also:
2024-6-30
Function gtk:flow-box-append (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget to append
Details:
Inserts the child widget into the flow box at the end of the flow box. If a sort function is set, the widget will actually be inserted at the calculated position.

Since 4.6
See also:
2024-6-30
Function gtk:flow-box-prepend (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget to prepend
Details:
Inserts the child widget into the flow box at the start of the flow box. If a sort function is set, the widget will actually be inserted at the calculated position.

Since 4.6
See also:
2024-6-30
Function gtk:flow-box-remove (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the flow box.
See also:
2024-6-30
Function gtk:flow-box-remove-all (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Details:
Removes all child widgets from the flow box.

Since 4.12
See also:
2024-6-30
Function gtk:flow-box-child-at-index (flowbox index)
Arguments:
flowbox -- a gtk:flow-box widget
index -- an integer with the position of the child widget
Returns:
The child widget, which will always be a gtk:flow-box-child widget or nil in case no child widget with the given index exists.
Details:
Gets the nth child widget in the flow box.
See also:
2024-6-30
Function gtk:flow-box-child-at-pos (flowbox x y)
Arguments:
flowbox -- a gtk:flow-box widget
x -- an integer with the x coordinate of the child widget
y -- an integer with the y coordinate of the child widget
Returns:
The child widget, which will always be a gtk:flow-box-child widget or nil in case no child widget exists for the given coordinates.
Details:
Gets the child widget in the flow box at the given coordinates.
See also:
#2024-4-14
Function gtk:flow-box-set-hadjustment (flowbox adjustment)
Arguments:
flowbox -- a gtk:flow-box widget
adjustment -- a gtk:adjustment object which should be adjusted when the focus is moved among the descendents of flowbox
Details:
Hooks up an adjustment to focus handling in the flow box. The adjustment is also used for autoscrolling during rubberband selection. See the gtk:scrolled-window-hadjustment function for a typical way of obtaining the adjustment, and the gtk:flow-box-set-vadjustment function for setting the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the flow box.
See also:
#2024-4-14
Function gtk:flow-box-set-vadjustment (flowbox adjustment)
Arguments:
flowbox -- a gtk:flow-box widget
adjustment -- a gtk:adjustment object which should be adjusted when the focus is moved among the descendents of flowbox
Details:
Hooks up an adjustment to focus handling in the flow box. The adjustment is also used for autoscrolling during rubberband selection. See the gtk:scrolled-window-vadjustment function for a typical way of obtaining the adjustment, and the gtk:flow-box-set-hadjustment function for setting the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box.
See also:
#2024-4-14
Callback gtk:flow-box-foreach-func
Syntax:
lambda (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:flow-box-child child widget
Details:
A callback function used by the gtk:flow-box-selected-foreach function. It will be called on every selected child widget of the flow box.
See also:
#2024-4-14
Function gtk:flow-box-selected-foreach (flowbox func)
Arguments:
flowbox -- a gtk:flow-box widget
func -- a gtk:flow-box-foreach-func callback function
Details:
Calls a function for each selected child widget in the flow box. Note that the selection cannot be modified from within this function.
See also:
#2024-4-14
Function gtk:flow-box-selected-children (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Returns:
The list containing the gtk:flow-box-child child widget for each selected child widget.
Details:
Creates a list of all selected children.
See also:
#2024-4-14
Function gtk:flow-box-select-child (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget of the flow box
Details:
Selects a single child widget of the flow box, if the selection mode allows it.
See also:
2024-6-30
Function gtk:flow-box-unselect-child (flowbox child)
Arguments:
flowbox -- a gtk:flow-box widget
child -- a gtk:widget child widget of the flow box
Details:
Unselects a single child widget of the flow box, if the selection mode allows it.
See also:
#2024-4-14
Function gtk:flow-box-select-all (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Details:
Select all children of the flow box, if the selection mode allows it.
See also:
#2024-4-14
Function gtk:flow-box-unselect-all (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Details:
Unselect all children of the flow box, if the selection mode allows it.
See also:
#2024-4-14
Callback gtk:flow-box-filter-func
Syntax:
lambda (child) => result
Arguments:
child -- a gtk:flow-box-child widget that may be filtered
result -- true if the child should be visible, false otherwise
Details:
A function that will be called whenever a child widget changes or is added. It lets you control if the child widget should be visible or not.
See also:
2024-6-30
Function gtk:flow-box-set-filter-func (flowbox func)
Arguments:
flowbox -- a gtk:flow-box widget
func -- a gtk:flow-box-filter-func callback function that lets you filter which children to show
Details:
By setting a filter function on the flow box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the children matching the search terms.

The func callback function will be called for each child widget after the call, and it will continue to be called each time a child changes, via the gtk:flow-box-child-changed function or when the gtk:flow-box-invalidate-filter function is called.

Note that using a filter function is incompatible with using a model. See the gtk:flow-box-bind-model function.
See also:
2024-6-30
Function gtk:flow-box-invalidate-filter (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Details:
Updates the filtering for all children in the flow box. Call this function when the result of the filter function on the flow box is changed due ot an external factor. For instance, this would be used if the filter function just looked for a specific search term, and the search entry with the string has changed.
See also:
2024-6-30
Callback gtk:flow-box-sort-func
Syntax:
lambda (child1 child2) => result
Arguments:
child1 -- a first gtk:flow-box-child widget
child2 -- a second gtk:flow-box-child widget
result -- an integer with a negative value if child1 should be before child2, zero if they are equal, and a positive value otherwise
Details:
A function to compare two children to determine which should come first.
See also:
2024-6-30
Function gtk:flow-box-set-sort-func (flowbox func)
Arguments:
flowbox -- a gtk:flow-box widget
func -- a gtk:flow-box-sort-func callback function for the sort function
Details:
By setting a sort function on the flow box, one can dynamically reorder the children of the flow box, based on the contents of the children.

The func callback function will be called for each child after the call, and will continue to be called each time a child changes, via the gtk:flow-box-child-changed function, and when the gtk:flow-box-invalidate-sort function is called.

Note that using a sort function is incompatible with using a model. See the gtk:flow-box-bind-model function.
See also:
2024-6-30
Function gtk:flow-box-invalidate-sort (flowbox)
Arguments:
flowbox -- a gtk:flow-box widget
Details:
Updates the sorting for all children in the flow box. Call this when the result of the sort function on the flow box is changed due to an external factor.
See also:
#2024-4-14
Callback gtk:flow-box-create-widget-func
Syntax:
lambda (object) => result
Arguments:
object -- a g:object instance with the item from the model for which to create a widget for
result -- a gtk:widget object that represents object
Details:
Called for flow boxes that are bound to a g:list-model object with the gtk:flow-box-bind-model function for each item that gets added to the model.
See also:
#2024-4-14
Function gtk:flow-box-bind-model (flowbox model func)
Arguments:
flowbox -- a gtk:flow-box widget
model -- a g:list-model object to be bound to flowbox
func -- a gtk:flow-box-create-widget-func callback function that creates widgets for items
Details:
Binds a model to the flow box. If the flow box was already bound to a model, that previous binding is destroyed.

The contents of the flow box are cleared and then filled with widgets that represent items from the model. The flow box is updated whenever the model changes. If the model argument is nil, the flow box is left empty.

It is undefined to add or remove widgets directly, for example, with the gtk:flow-box-insert function, while the flow box is bound to a model.

Note that using a model is incompatible with the filtering and sorting functionality in the flow box. When using a model, filtering and sorting should be implemented by the model.
See also:
#2024-4-14

GtkStack

GEnum gtk:stack-transition-type
Declaration:
(gobject:define-genum "GtkStackTransitionType" stack-transition-type
  (:export t
   :type-initializer "gtk_stack_transition_type_get_type")
  (:none 0)
  (:crossfade 1)
  (:slide-right 2)
  (:slide-left 3)
  (:slide-up 4)
  (:slide-down 5)
  (:slide-left-right 6)
  (:slide-up-down 7)
  (:over-up 8)
  (:over-down 9)
  (:over-left 10)
  (:over-right 11)
  (:under-up 12)
  (:under-down 13)
  (:under-left 14)
  (:under-right 15)
  (:over-up-down 16)
  (:over-down-up 17)
  (:over-left-right 18)
  (:over-right-left 19)
  (:rotate-left 20)
  (:rotate-right 21)
  (:rotate-left-right 22))  
Values:
:none
No transition
:crossfade
A cross fade.
:slide-right
Slide from left to right.
:slide-left
Slide from right to left.
:slide-up
Slide from bottom up.
:slide-down
Slide from top down.
:slide-left-right
Slide from left or right according to the children order.
:slide-up-down
Slide from top down or bottom up according to the order.
:over-up
Cover the old page by sliding up.
:over-down
Cover the old page by sliding down.
:over-left
Cover the old page by sliding to the left.
:over-right
Cover the old page by sliding to the right.
:under-up
Uncover the new page by sliding up.
:under-down
Uncover the new page by sliding down.
:under-left
Uncover the new page by sliding to the left.
:under-right
Uncover the new page by sliding to the right.
:over-up-down
Cover the old page sliding up or uncover the new page sliding down, according to order.
:over-down-up
Cover the old page sliding down or uncover the new page sliding up, according to order.
:over-left-right
Cover the old page sliding left or uncover the new page sliding right, according to order.
:over-right-left
Cover the old page sliding right or uncover the new page sliding left, according to order.
:rotate-left
Pretend the pages are sides of a cube and rotate that cube to the left.
:rotate-right
Pretend the pages are sides of a cube and rotate that cube to the right.
:rotate-left-right
Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order.
Details:
These enumeration values describe the possible transitions between pages in a gtk:stack widget.
See also:
2024-4-14
Class gtk:stack-page
Superclasses:
gtk:accessible, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write / Construct only)
The child widget of the page.
icon-name
The icon-name property of type :string (Read / Write)
The icon name of the child page.
Default value: nil
name
The name property of type :string (Read / Write)
The name of the child page.
Default value: nil
needs-attention
The needs-attention property of type :boolean (Read / Write)
Sets a flag specifying whether the page requires the user attention. This is used by the gtk:stack-switcher widget to change the appearance of the corresponding button when a page needs attention and it is not the current one.
Default value: false
title
The title property of type :string (Read / Write)
The title of the child page.
Default value: nil
use-underline
The use-underline property of type :boolean (Read / Write)
If set, an underline in the title indicates the next character should be used for the mnemonic accelerator key.
Default value: false
visible
The visible property of type :boolean (Read / Write)
Whether this page is visible.
Default value: true
Slot Access Functions:
Details:
The gtk:stack-page class is an auxiliary class used by the gtk:stack class.
See also:
2024-4-14
Accessor gtk:stack-page-child (object)
Syntax:
(gtk:stack-page-child object) => child
Arguments:
object -- a gtk:stack-page object
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:stack-page class. The gtk:stack-page-child function returns the child widget of the page.
See also:
2024-4-14
Accessor gtk:stack-page-icon-name (object)
Syntax:
(gtk:stack-page-icon-name object) => name
(setf (gtk:stack-page-icon-name object) name)
Arguments:
object -- a gtk:stack-page object
name -- a string with the icon name of the child page
Details:
Accessor of the icon-name slot of the gtk:stack-page class. The gtk:stack-page-icon-name function returns the icon name of the child page. The (setf gtk:stack-page-icon-name) function sets the icon name.
See also:
2024-4-14
Accessor gtk:stack-page-name (object)
Syntax:
(gtk:stack-page-name object) => name
(setf (gtk:stack-page-name object) name)
Arguments:
object -- a gtk:stack-page object
name -- a string with the name of the child page
Details:
Accessor of the name slot of the gtk:stack-page class. The gtk:stack-page-name function returns the name of the page. The (setf gtk:stack-page-name) function sets the name.
See also:
2024-4-14
Accessor gtk:stack-page-needs-attention (object)
Syntax:
(gtk:stack-page-needs-attention object) => setting
(setf (gtk:stack-page-needs-attention object) setting)
Arguments:
object -- a gtk:stack-page object
setting -- a boolean whether the page requires the user attention
Details:
Accessor of the needs-attention slot of the gtk:stack-page class. The gtk:stack-page-needs-attention function returns whether the page is marked as "needs attention". The (setf gtk:stack-page-needs-attention) function sets sets a flag specifying whether the page requires the user attention.

This is used by the gtk:stack-switcher widget to change the appearance of the corresponding button when a page needs attention and it is not the current one.
See also:
2024-4-14
Accessor gtk:stack-page-title (object)
Syntax:
(gtk:stack-page-title object) => title
(setf (gtk:stack-page-title object) title)
Arguments:
object -- a gtk:stack-page object
title -- a string with the title of the child page
Details:
Accessor of the title slot of the gtk:stack-page class. The gtk:stack-page-title function gets the page title. The (setf gtk:stack-page-title) function sets the page title.
See also:
2024-4-14
Accessor gtk:stack-page-use-underline (object)
Syntax:
(gtk:stack-page-use-underline object) => setting
(setf (gtk:stack-page-use-underline object) setting)
Arguments:
object -- a gtk:stack-page object
setting -- a boolean if set, an underline in the title indicates the next character should be used for the mnemonic accelerator key
Details:
Accessor of the use-underline slot of the gtk:stack-page class. The gtk:stack-page-use-underline function gets whether underlines in the page title indicate mnemonics. The (setf gtk:stack-page-use-underline) function sets the property.
See also:
2024-4-14
Accessor gtk:stack-page-visible (object)
Syntax:
(gtk:stack-page-visible object) => setting
(setf (gtk:stack-page-visible object) setting)
Arguments:
object -- a gtk:stack-page object
setting -- a boolean whether this page is visible
Details:
Accessor of the visible slot of the gtk:stack-page class. The gtk:stack-page-visible function returns whether the page is visible in its stack. The (setf gtk:stack-page-visible) function sets the property. This is independent from the visible property of its widget.
See also:
2024-4-14
Class gtk:stack
Superclasses:
Documented Subclasses:
None
Direct Slots:
hhomogeneous
The hhomogeneous property of type :boolean (Read / Write)
True if the stack allocates the same width for all children.
Default value: true
interpolate-size
The interpolate-size property of type :boolean (Read / Write)
Whether or not the size should smoothly change when changing between differently sized children.
Default value: false
pages
The pages property of type gtk:selection-model (Read)
A selection model with the pages of the stack. Returns a g:list-model object that contains the pages of the stack, and can be used to keep an up-to-date view. The model also implements the gtk:selection-model object and can be used to track and modify the visible page.
transition-duration
The transition-duration property of type :uint (Read / Write)
The animation duration, in milliseconds.
Default value: 200
transition-running
The transition-running property of type :boolean (Read)
Whether or not the transition is currently running.
Default value: false
transition-type
The transition-type property of type gtk:stack-transition-type (Read / Write)
The type of animation used to transition.
Default value: :none
vhomogeneous
The vhomogeneous property of type :boolean (Read / Write)
True if the stack allocates the same height for all children.
Default value: true
visible-child
The visible-child property of type gtk:widget (Read / Write)
The widget currently visible in the stack.
visible-child-name
The visible-child-name property of type :string (Read / Write)
The name of the widget currently visible in the stack.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:stack widget is a container which only shows one of its children at a time. In contrast to the gtk:notebook widget, the gtk:stack widget does not provide a means for users to change the visible child. Instead, the gtk:stack-switcher widget can be used with the gtk:stack widget to provide this functionality.

Figure: GtkStack

Transitions between pages can be animated as slides or fades. This can be controlled with the gtk:stack-transition-type function. These animations respect the gtk-enable-animations setting.

The gtk:stack widget maintains a gtk:stack-page object for each added child widget, which holds additional per-child properties. You obtain the gtk:stack-page object for a child widget with the gtk:stack-page function.
GtkStack as GtkBuildable:
To set child-specific properties in a .ui file, create gtk:stack-page objects explicitly, and set the child widget as a property on it:
<object class="GtkStack" id="stack">
  <child>
    <object class="GtkStackPage">
      <property name="name">page1</property>
      <property name="title">In the beginning…</property>
      <property name="child">
        <object class="GtkLabel">
          <property name="label">It was dark</property>
        </object>
      </property>
    </object>
  </child>    
CSS nodes:
The gtk:stack implementation has a single CSS node named stack.
Accessibility:
The gtk:stack implementation uses the :tab-panel role of the gtk:accessible-role enumeration for the stack pages, which are the accessible parent objects of the child widgets.
See also:
2023-8-8
Accessor gtk:stack-hhomogeneous (object)
Syntax:
(gtk:stack-hhomogeneous object) => homogeneous
(setf (gtk:stack-hhomogeneous object) homogeneous)
Arguments:
object -- a gtk:stack widget
homogeneous -- true to make stack horizontally homogeneous
Details:
Accessor of the hhomogeneous slot of the gtk:stack class. The gtk:stack-hhomogeneous function gets whether the stack is horizontally homogeneous. The (setf gtk:stack-hhomogeneous) function sets the stack to be horizontally homogeneous or not.

If the stack is homogeneous, the stack will request the same width for all its children. If it is not, the stack may change width when a different child becomes visible.
See also:
2024-4-15
Accessor gtk:stack-interpolate-size (object)
Syntax:
(gtk:stack-interpolate-size object) => interpolate
(setf (gtk:stack-interpolate-size object) interpolate)
Arguments:
object -- a gtk:stack widget
interpolate -- true if child sizes are interpolated
Details:
Accessor of the interpolate-size slot of the gtk:stack class. The gtk:stack-interpolate-size function returns whether the stack is set up to interpolate between the sizes of children on page switch. The (setf gtk:stack-interpolate-size) function sets whether or not stack will interpolate its size when changing the visible child.

If the interpolate-size property is set to true, the stack will interpolate its size between the current one and the one it will take after changing the visible child, according to the set transition duration.
See also:
2024-4-15
Accessor gtk:stack-pages (object)
Syntax:
(gtk:stack-pages object) => pages
Arguments:
object -- a gtk:stack widget
pages -- a gtk:selection-model object with the stacks pages
Details:
Accessor of the pages slot of the gtk:stack class. The gtk:stack-pages function returns a g:list-model object that contains the pages of the stack, and can be used to keep an up-to-date view. The model also implements the gtk:selection-model object and can be used to track and modify the visible page.
See also:
2024-4-15
Accessor gtk:stack-transition-duration (object)
Syntax:
(gtk:stack-transition-duration object) => duration
(setf (gtk:stack-transition-duration object) duration)
Arguments:
object -- a gtk:stack widget
duration -- an unsigned integer with the duration, in milliseconds
Details:
Accessor of the transition-duration slot of the gtk:stack class. The gtk:stack-transition-duration function returns the amount of time in milliseconds that transitions between pages in the stack will take. The (setf gtk:stack-transition-duration) function sets the duration.
See also:
2024-4-15
Accessor gtk:stack-transition-running (object)
Syntax:
(gtk:stack-transition-running object) => running
Arguments:
object -- a gtk:stack widget
Details:
Accessor of the transition-running slot of the gtk:stack class. The gtk:stack-transition-running function returns whether the stack is currently in a transition from one page to another.
See also:
2024-4-15
Accessor gtk:stack-transition-type (object)
Syntax:
(gtk:stack-transition-type object) => setting
(setf (gtk:stack-transition-type object) setting)
Arguments:
object -- a gtk:stack widget
setting -- a value of the gtk:stack-transition-type enumeration
Details:
Accessor of the transition-type slot of the gtk:stack class. The gtk:stack-transition-type function gets the type of animation that will be used for transitions between pages in the stack. The (setf gtk:stack-transition-type) function sets the type of animation that will be used for transitions between pages in the stack. Available types include various kinds of fades and slides.

The transition type can be changed without problems at runtime, so it is possible to change the animation based on the page that is about to become current.
See also:
2024-4-15
Accessor gtk:stack-vhomogeneous (object)
Syntax:
(gtk:stack-vhomogeneous object) => homogeneous
(setf (gtk:stack-vhomogeneous object) homogeneous)
Arguments:
object -- a gtk:stack widget
homogeneous -- true to make the stack vertically homogeneous
Details:
Accessor of the vhomogeneous slot of the gtk:stack class. The gtk:stack-vhomogeneous function gets whether the stack is vertically homogeneous. The (setf gtk:stack-vhomogeneous) function sets the stack to be vertically homogeneous or not.

If the stack is homogeneous, the stack will request the same height for all its children. If it is not, the stack may change height when a different child becomes visible.
See also:
2024-4-15
Accessor gtk:stack-visible-child (object)
Syntax:
(gtk:stack-visible-child object) => child
(setf (gtk:stack-visible-child object) child)
Arguments:
object -- a gtk:stack widget
child -- a gtk:widget child widget of the stack
Details:
Accessor of the visible-child slot of the gtk:stack class. The gtk:stack-visible-child function gets the currently visible child widget of the stack, or nil if there are no visible children. The (setf gtk:stack-visible-child) function makes the child widget the visible child widget of the stack.

If widget is different from the currently visible child widget, the transition between the two will be animated with the current transition type of stack.

Note that the child widget has to be visible itself, see the gtk:widget-visible function, in order to become the visible child of the stack.
See also:
2024-4-15
Accessor gtk:stack-visible-child-name (object)
Syntax:
(gtk:stack-visible-child-name object) => name
(setf (gtk:stack-visible-child-name object) name)
Arguments:
object -- a gtk:stack widget
name -- a string with the name of the visible child of the stack
Details:
Accessor of the visible-child-name slot of the gtk:stack class. The gtk:stack-visible-child-name function returns the name of the currently visible child of the stack, or nil if there is no visible child. The (setf gtk:stack-visible-child-name) function makes the child widget with the given name visible.

If the child widget is different from the currently visible child, the transition between the two will be animated with the current transition type of stack.

Note that the child widget has to be visible itself, see the gtk:widget-visible function, in order to become the visible child of the stack.
See also:
2024-4-15
Function gtk:stack-new ()
Returns:
The new gtk:stack widget.
Details:
Creates a new stack.
See also:
2024-4-15
Function gtk:stack-add-named (stack child name)
Arguments:
stack -- a gtk:stack widget
child -- a gtk:widget child page to add
name -- a string with the name for the child page
Details:
Adds a child page to the stack. The child page is identified by name.
See also:
#2023-8-8
Function gtk:stack-add-titled (stack child name title)
Arguments:
stack -- a gtk:stack widget
child -- a gtk:widget child widget to add
name -- a string with the name for the child page
title -- a string with a human readable title for the child page
Details:
Adds a child page to the stack. The child page is identified by name. The title will be used by the gtk:stack-switcher widget to represent the child page in a tab bar, so it should be short.
See also:
2023-8-8
Function gtk:stack-remove (stack child)
Arguments:
stack -- a gtk:stack widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the stack.
See also:
#2023-8-8
Function gtk:stack-child-by-name (stack name)
Arguments:
stack -- a gtk:stack widget
name -- a string with the name for the child page to find
Returns:
The requested gtk:widget child page of the stack.
Details:
Finds the child page of the stack with the name given as the argument. Returns nil if there is no child page with this name.
See also:
#2023-8-8
Function gtk:stack-page (stack child)
Arguments:
stack -- a gtk:stack widget
child -- a gtk:widget child widget
Returns:
The gtk:stack-page object for the child widget
Details:
Returns the gtk:stack-page object for the child widget.
See also:
2024-4-15
Function gtk:stack-set-visible-child-full (stack name transition)
Arguments:
stack -- a gtk:stack widget
name -- a string with the name of the child page to make visible
transition -- a value of the gtk:stack-transition-type enumeration to use
Details:
Makes the child page with the given name visible. Note that the child page has to be visible itself, see the gtk:widget-visible function, in order to become the visible child page of the stack.
See also:
#2023-8-8

GtkStackSwitcher

Class gtk:stack-switcher
Superclasses:
Documented Subclasses:
None
Direct Slots:
stack
The stack property of type gtk:stack (Read / Write)
The stack to control.
Returned by:
Slot Access Functions:
Details:
The gtk:stack-switcher widget acts as a controller for a gtk:stack widget. It shows a row of buttons to switch between the various pages of the associated stack widget.

Figure: GtkStackSwitcher

All the content for the buttons comes from the child properties of the gtk:stack widget. The button visibility in a gtk:stack-switcher widget is controlled by the visibility of the child widget in the gtk:stack widget.

It is possible to associate multiple gtk:stack-switcher widgets with the same gtk:stack widget.
CSS nodes:
The gtk:stack-switcher implementation has a single CSS node named stackswitcher and .stack-switcher style class. When circumstances require it, the gtk:stack-switcher widget adds the .needs-attention style class to the widgets representing the stack pages.
Accessibility:
The gtk:stack-switcher implementation uses the :tab-list role and uses the :tab role of the gtk:accessible-role enumeration for its buttons.
See also:
2024-4-15
Accessor gtk:stack-switcher-stack (object)
Syntax:
(gtk:stack-switcher-stack object) => stack
(setf (gtk:stack-switcher-stack object) stack)
Arguments:
object -- a gtk:stack-switcher widget
stack -- a gtk:stack widget
Details:
Accessor of the stack slot of the gtk:stack-switcher class. The gtk:stack-switcher-stack function retrieves the stack. The (setf gtk:stack-switcher-stack) function sets the stack to control.
See also:
2024-4-15
Function gtk:stack-switcher-new ()
Returns:
The new gtk:stack-switcher widget.
Details:
Creates a new stack switcher.
See also:
2024-4-15

GtkStackSidebar

Class gtk:stack-sidebar
Superclasses:
Documented Subclasses:
None
Direct Slots:
stack
The stack property of type gtk:stack (Read / Write)
Associated stack for this stack sidebar.
Returned by:
Slot Access Functions:
Details:
The gtk:stack-sidebar widget enables you to quickly and easily provide a consistent "sidebar" object for your user interface.

Figure: GtkStackSidebar

In order to use the gtk:stack-sidebar widget, you simply use the gtk:stack widget to organize your UI flow, and add the sidebar to your sidebar area. You can use the gtk:stack-sidebar-stack function to connect the gtk:stack-sidebar widget to the gtk:stack widget.
CSS nodes:
The gtk:stack-sidebar implementation has a single CSS node with name stacksidebar and .sidebar style class. When circumstances require it, the gtk:stack-sidebar widget adds the .needs-attention style class to the widgets representing the stack pages.
See also:
2023-8-9
Accessor gtk:stack-sidebar-stack (object)
Syntax:
(gtk:stack-sidebar-stack object) => stack
(setf (gtk:stack-sidebar-stack object) stack)
Arguments:
object -- a gtk:stack-sidebar widget
stack -- a gtk:stack widget
Details:
Accessor of the stack slot of the gtk:stack-sidebar class. The gtk:stack-sidebar-stack function retrieves the stack. The (setf gtk:stack-sidebar-stack) function sets the stack associated with this stack sidebar.

The stack sidebar will automatically update according to the order (packing) and items within the given stack.
See also:
2023-8-9
Function gtk:stack-sidebar-new ()
Returns:
The new gtk:stack-sidebar widget.
Details:
Creates a new stack sidebar.
See also:
2023-8-9

GtkActionBar

Class gtk:action-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
revealed
The revealed property of type :boolean (Read / Write)
Controls whether the action bar shows its contents or not.
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:action-bar widget is designed to present contextual actions. It is expected to be displayed below the content and expand horizontally to fill the area.

Figure: GtkActionBar

It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space.
GtkActionBar as GtkBuildable:
The gtk:action-bar implementation of the gtk:buildable interface supports adding children at the start or end sides by specifying "start" or "end" as the "type" attribute of a <child> element, or setting the center widget by specifying "center" value.
CSS nodes:
actionbar
╰── revealer
    ╰── box
        ├── box.start
        │   ╰── [start children]
        ├── [center widget]
        ╰── box.end
            ╰── [end children]    
The gtk:action-bar implementation has a single CSS node with name actionbar. It contains a revealer subnode, which contains a box subnode, which contains two box subnodes at the start and end of the action bar, with start and end style classes respectively, as well as a center node that represents the center child. Each of the boxes contains children packed for that side.
See also:
2024-4-21
Accessor gtk:action-bar-revealed (object)
Syntax:
(gtk:action-bar-revealed object) => revealed
(setf (gtk:action-bar-revealed object) revealed)
Arguments:
object -- a gtk:action-bar widget
revealed -- a boolean whether the action bar shows its contents
Details:
Accessor of the revealed slot of the gtk:action-bar class. Changing the revealed property will make the action bar reveal (true) or conceal (false) itself via a sliding transition.
Notes:
This does not show or hide the action bar in the visible property sense, so revealing has no effect if the visible property is false.
See also:
2023-8-9
Function gtk:action-bar-new ()
Returns:
The new gtk:action-bar widget.
Details:
Creates a new action bar.
See also:
2023-8-9
Function gtk:action-bar-pack-start (actionbar child)
Arguments:
actionbar -- a gtk:action-bar widget
child -- a gtk:widget child widget to be added to actionbar
Details:
Adds the child widget to the action bar, packed with reference to the start of the action bar.
See also:
2024-4-21
Function gtk:action-bar-pack-end (actionbar child)
Arguments:
actionbar -- a gtk:action-bar widget
child -- a gtk:widget child widget to be added to actionbar
Details:
Adds the child widget to the action bar, packed with reference to the end of the action bar.
See also:
2024-4-21
Function gtk:action-bar-remove (actionbar child)
Arguments:
actionbar -- a gtk:action-bar widget
child -- a gtk:widget child widget to be removed
Details:
Removes a child widget from the action bar.
See also:
#2023-8-9
Function gtk:action-bar-center-widget (actionbar)
Syntax:
(gtk:action-bar-center-widget actionbar) => widget
(setf (gtk:action-bar-center-widget actionbar) widget)
Arguments:
actionbar -- a gtk:action-bar widget
widget -- a gtk:widget object to use for the center widget
Details:
The gtk:action-bar-center-widget function retrieves the center widget of the action bar. The (setf gtk:action-bar-center-widget) function sets the center widget for the action bar.
See also:
2024-4-21

GtkHeaderBar

Class gtk:header-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
decoration-layout
The decoration-layout property of type :string (Read / Write)
The decoration layout for buttons. If this property is not set, the gtk-decoration-layout setting is used. See the gtk:header-bar-decoration-layout function for information about the format of this string.
Default value: nil
show-title-buttons
The show-title-buttons property of type :boolean (Read / Write)
Whether to show title buttons like Close, Minimize, Maximize. Which buttons are actually shown and where is determined by the decoration-layout property, and by the state of the window, for example, a Close button will not be shown if the window cannot be closed.
Default value: true
title-widget
The title-widget property of type gtk:widget (Read / Write)
Title widget to display.
Returned by:
Slot Access Functions:
Details:
The gtk:header-bar widget is similar to a horizontal gtk:box widget. It allows children to be placed at the start or the end. In addition, it allows a title and subtitle to be displayed.

Figure: GtkHeaderBar

The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space.

The gtk:header-bar widget can add typical window frame controls, such as Minimize, Maximize and Close buttons, or the window icon.

For these reasons, the gtk:header-bar widget is the natural choice for use as the custom titlebar widget of a gtk:window widget, see the gtk:window-titlebar function, as it gives features typical of titlebars while allowing the addition of child widgets.
GtkHeaderBar as GtkBuildable:
The gtk:header-bar widget implementation of the gtk:buildable interface supports adding children at the start or end sides by specifying "start" or "end" as the "type" attribute of a <child> element, or setting the title widget by specifying "title" value.

By default the gtk:header-bar widget uses a gtk:label widget displaying the title of the window it is contained in as the title widget, equivalent to the following UI definition:
<object class="GtkHeaderBar">
  <property name="title-widget">
    <object class="GtkLabel">
      <property name="label" translatable="yes">Label</property>
      <property name="single-line-mode">True</property>
      <property name="ellipsize">end</property>
      <property name="width-chars">5</property>
      <style>
        <class name="title"/>
      </style>
    </object>
  </property>
</object>    
CSS nodes:
headerbar
╰── windowhandle
    ╰── box
        ├── box.start
        │   ├── windowcontrols.start
        │   ╰── [other children]
        ├── [Title Widget]
        ╰── box.end
            ├── [other children]
            ╰── windowcontrols.end    
The gtk:header-bar implementation has a CSS node with the name headerbar. It contains a windowhandle subnode, which contains a box subnode, which contains two box subnodes at the start and end of the header bar, as well as a center node that represents the title.

Each of the boxes contains a windowcontrols subnode, see the gtk:window-controls widget for details, as well as other children.
Accessibility:
The gtk:header-bar implementation uses the :group role of the gtk:accessible-role enumeration.
See also:
2025-2-22
Accessor gtk:header-bar-decoration-layout (object)
Syntax:
(gtk:header-bar-decoration-layout object) => layout
(setf (gtk:header-bar-decoration-layout object) layout)
Arguments:
object -- a gtk:header-bar widget
layout -- a string for the decoration layout, or nil to unset the layout
Details:
Accessor of the decoration-layout slot of the gtk:header-bar class. The gtk:header-bar-decoration-layout function gets the decoration layout. The (setf gtk:header-bar-decoration-layout) function sets the decoration layout for the header bar, overriding the gtk-decoration-layout setting.

There can be valid reasons for overriding the setting, such as a header bar design that does not allow for buttons to take room on the right, or only offers room for a single Close button. Split header bars are another example for overriding the setting.

The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are "minimize", "maximize", "close", "icon" for the window icon and "menu" for a menu button for the fallback application menu.

For example, "menu:minimize,maximize,close" specifies a Menu on the left, and Minimize, Maximize and Close buttons on the right.
See also:
2025-2-22
Accessor gtk:header-bar-show-title-buttons (object)
Syntax:
(gtk:header-bar-show-title-buttons object) => setting
(setf (gtk:header-bar-show-title-buttons object) setting)
Arguments:
object -- a gtk:header-bar widget
setting -- true if title buttons are shown
Details:
Accessor of the show-title-buttons slot of the gtk:header-bar class. The gtk:header-bar-show-title-buttons function returns whether the header bar shows the standard window title buttons. The (setf gtk:header-bar-show-title-buttons) function sets whether the header bar shows the standard window title buttons including Close, Maximize, and Minimize.
See also:
2025-2-22
Accessor gtk:header-bar-title-widget (object)
Syntax:
(gtk:header-bar-title-widget object) => title
(setf (gtk:header-bar-title-widget object) title)
Arguments:
object -- a gtk:header-bar widget
title -- a gtk:widget title widget for the header bar
Details:
Accessor of the title-widget slot of the gtk:header-bar class. The gtk:header-bar-title-widget function retrieves the title widget of the header bar. The (setf gtk:header-bar-title-widget) function sets the title widget.

When set to nil, the header bar will display the title of the window it is contained in. The title should help a user identify the current view. To achieve the same style as the builtin title, use the title style class. You should set the title widget to nil, for the window title label to be visible again.
See also:
2025-2-22
Function gtk:header-bar-new ()
Returns:
The new gtk:header-bar widget.
Details:
Creates a new header bar.
See also:
2025-2-22
Function gtk:header-bar-pack-start (header child)
Arguments:
header -- a gtk:header-bar widget
child -- a gtk:widget child widget to be added to the header bar
Details:
Adds a child widget to the header bar, packed with reference to the start of the header bar.
Examples:
Code fragment for a header bar with two buttons. The Cancel button is placed on the left side and the Done button on the right side of the header bar.
(let (...
      (header (make-instance 'gtk:header-bar
                             :show-title-buttons nil))
      (button (make-instance 'gtk:button
                             :label "_Done"
                             :use-underline t
                             :sensitive nil))
      (cancel (make-instance 'gtk:button
                             :label "_Cancel"
                             :use-underline t))
      ...)
  ...
  (gtk:header-bar-pack-start header cancel)
  (gtk:header-bar-pack-end header button)
  ... )    
See also:
2025-2-22
Function gtk:header-bar-pack-end (header child)
Arguments:
header -- a gtk:header-bar widget
child -- a gtk:widget child widget to be added to the header bar
Details:
Adds a child widget to the header bar, packed with reference to the end of the header bar. See the gtk:header-bar-pack-start function for an example.
See also:
2025-2-22
Function gtk:header-bar-remove (headerbar child)
Arguments:
header -- a gtk:header-bar widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the header bar, after it has been added with the gtk:header-bar-pack-start, gtk:header-bar-pack-end or gtk:header-bar-title-widget functions.
See also:
2025-2-22

GtkOverlay

Class gtk:overlay
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The main child widget of the overlay.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:overlay widget contains a single main widget, on top of which it can place overlay widgets.

Figure: GtkOverlay

The position of each overlay widget is determined by its halign and valign properties. For example, an overlay widget with both alignments set to :start will be placed at the top left corner of the main widget, whereas an overlay widget with the halign property set to :center and the valign property set to :end will be placed a the bottom edge of the main widget, horizontally centered. The position can be adjusted by setting the margin properties of the overlay widget to non-zero values.

More complicated placement of overlay widgets is possible by connecting to the "get-child-position" signal.

The minimum and natural sizes of an overlay widget are those of its main child. The sizes of overlay children are not considered when measuring these preferred sizes.
GtkOverlay as GtkBuildable:
The gtk:overlay implementation of the gtk:buildable interface supports placing a child widget as an overlay by specifying "overlay" as the "type" attribute of a <child> element.
CSS nodes:
The gtk:overlay implementation has a single CSS node with the name overlay. Overlay children whose alignments cause them to be positioned at an edge get the .left, .right, .top, and/or .bottom style classes according to their position.
Signal Details:
The "get-child-position" signal
lambda (overlay widget allocation)    :run-last      
overlay
The gtk:overlay widget which emitted the signal.
widget
The gtk:widget overlay widget to position.
allocation
Return location of type gdk:rectangle for the allocation.
Returns
True if allocation has been filled.
The signal is emitted to determine the position and size of any overlay widgets. A handler for this signal should fill allocation with the desired position and size for widget, relative to the main child of the overlay. The default handler for this signal uses the halign and valign properties of the widget to determine the position and gives the widget its natural size, except that an alignment of :fill will cause the overlay to be full-width/height. If the main child is a gtk:scrolled-window widget, the overlays are placed relative to its contents.
2024-10-2
Accessor gtk:overlay-child (object)
Syntax:
(gtk:overlay-child object) => child
(setf (gtk:overlay-child object) child)
Arguments:
object -- a gtk:overlay widget
child -- a gtk:widget main widget
Details:
Accessor of the child slot of the gtk:overlay class. The gtk:overlay-child function gets the main widget of the overlay. The (setf gtk:overlay-child) function sets the main widget.
See also:
2024-10-2
Function gtk:overlay-new ()
Returns:
The new gtk:overlay widget.
Details:
Creates a new overlay.
See also:
2024-10-2
Function gtk:overlay-add-overlay (overlay widget)
Arguments:
overlay -- a gtk:overlay widget
widget -- a gtk:widget overlay widget to be added
Details:
Adds an overlay widget to the overlay. The overlay widget will be stacked on top of the main widget added with the gtk:overlay-child function. The position at which the overlay widget is placed is determined from its halign and valign properties.
See also:
2024-10-2
Function gtk:overlay-remove-overlay (overlay widget)
Arguments:
overlay -- a gtk:overlay widget
widget -- a gtk:widget overlay widget to be removed
Details:
Removes an overlay widget that was added with the gtk:overlay-add-overlay function.
See also:
2024-10-2
Function gtk:overlay-measure-overlay (overlay widget)
Syntax:
(gtk:overlay-measure-overlay overlay widget) => measure
(setf (gtk:overlay-measure-overlay overlay widget) measure)
Arguments:
overlay -- a gtk:overlay widget
widget -- a gtk:widget overlay widget
measure -- a boolean whether the overlay widget should be measured
Details:
The gtk:overlay-measure-overlay function gets whether the size of the overlay widget is included in the measurement of the overlay. The (setf gtk:overlay-measure-overlay) function sets the property.

The overlay will request the size of the largest overlay widget that has this property set to true. Children who are not included may be drawn outside of the allocation of the overlay if they are too large.
See also:
2024-10-2
Function gtk:overlay-clip-overlay (overlay widget)
Syntax:
(gtk:overlay-clip-overlay overlay widget) => clip
(setf (gtk:overlay-clip-overlay overlay widget) clip)
Arguments:
overlay -- a gtk:overlay widget
widget -- a gtk:widget overlay widget
clip -- a boolean whether the overlay widget should be clipped
Details:
The gtk:overlay-clip-overlay function gets whether the overlay widget should be clipped within the overlay. The (setf gtk:overlay-clip-overlay) function sets the property.
See also:
2024-10-2

GtkPaned

Class gtk:paned
Superclasses:
Documented Subclasses:
None
Direct Slots:
end-child
The end-child property of type gtk:widget (Read / Write)
The second child widget.
max-position
The max-position property of type :int (Read)
The largest possible value for the position property. This property is derived from the size and shrinkability of the children of the paned widget.
Allowed values: >= 0
Default value: 2147483647
min-position
The min-position property of type :int (Read)
The smallest possible value for the position property. This property is derived from the size and shrinkability of the children of the paned widget.
Allowed values: >= 0
Default value: 0
position
The position property of type :int (Read / Write)
Position of the paned separator in pixels, 0 means all the way to the left/top.
Allowed values: >= 0
Default value: 0
position-set
The position-set property of type :boolean (Read / Write)
True if the position property should be used.
Default value: false
resize-end-child
The resize-end-child property of type :boolean (Read / Write)
Determines whether the second child expands and shrinks along with the paned widget.
Default value: true
resize-start-child
The resize-start-child property of type :boolean (Read / Write)
Determines whether the first child expands and shrinks along with the paned widget.
Default value: true
shrink-end-child
The shrink-end-child property of type :boolean (Read / Write)
Determines whether the second child can be made smaller than its requisition.
Default value: true
shrink-start-child
The shrink-start-child property of type :boolean (Read / Write)
Determines whether the first child can be made smaller than its requisition.
Default value: true
start-child
The start-child property of type gtk:widget (Read / Write)
The first child widget.
wide-handle
The wide-handle property of type :boolean (Read / Write)
Setting this property to true indicates that the paned widget needs to provide stronger visual separation, for example, because it separates between two notebooks, whose tab rows would otherwise merge visually.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:paned widget has two panes, arranged either horizontally or vertically. The division between the two panes is adjustable by the user by dragging a handle.

Figure: GtkPaned

Child widgets are added to the panes of the paned widget with the gtk:paned-start-child and gtk:paned-end-child functions. The division between the two children is set by default from the size requests of the children, but it can be adjusted by the user.

A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. The space in which the separator is called the gutter. Often, it is useful to put each child widget inside a gtk:frame widget with the shadow type set to the :in value so that the gutter appears as a ridge. No separator is drawn if one of the children is missing.

Each child widget has two properties that can be set, the resize and shrink properties. If the resize property is true, then when the gtk:paned widget is resized, that child widget will expand or shrink along with the paned widget. If the shrink property is true, then that child widget can be made smaller than its requisition by the user. Setting the shrink property to false allows the application to set a minimum size. If the resize property is false for both children, then this is treated as if the resize property is true for both children.

The application can set the position of the slider as if it were set by the user, by calling the gtk:paned-position function.
CSS nodes:
paned
├── <child>
├── separator[.wide]
╰── <child>    
The gtk:paned implementation has a main CSS node with name paned, and a subnode for the separator with name separator. The subnode gets a .wide style class when the paned is supposed to be wide. In horizontal orientation, the nodes of the children are always arranged from left to right. So :first-child will always select the leftmost child widget, regardless of text direction.
Examples:
Creating a paned widget with minimum sizes.
(let ((frame1 (make-instance 'gtk:frame
                             :width-request 50))
      (frame2 (make-instance 'gtk:frame
                             :width-request 50))
      (paned (make-instance 'gtk:paned
                            :orientation :horizontal
                            :start-child frame1
                            :end-child frame2
                            :resize-start-child t
                            :width-request 250
                            :height-request 150)))
    ... )    
Signal Details:
The "accept-position" signal
lambda (widget)    :action      
widget
The gtk:paned widget that received the signal.
The signal is a keybinding signal which gets emitted to accept the current position of the handle when moving it using key bindings. The default binding for this signal is the Return or Space key.
The "cancel-position" signal
lambda (widget)    :action      
widget
The gtk:paned widget that received the signal.
The signal is a keybinding signal which gets emitted to cancel moving the position of the handle using key bindings. The position of the handle will be reset to the value prior to moving it. The default binding for this signal is the Escape key.
The "cycle-child-focus" signal
lambda (widget reversed)    :action      
widget
The gtk:paned widget that received the signal.
reversed
The boolean whether cycling backward or forward.
The signal is a keybinding signal which gets emitted to cycle the focus between the children of the paned widget. The default binding is the F6 key.
The "cycle-handle-focus" signal
lambda (widget reversed)    :action      
widget
The gtk:paned widget that received the signal.
reversed
The boolean whether cycling backward or forward.
The signal is a keybinding signal which gets emitted to cycle whether the paned widget should grab focus to allow the user to change position of the handle by using key bindings. The default binding for this signal is the F8 key.
The "move-handle" signal
lambda (widget scrolltype)    :action      
widget
The gtk:paned widget that received the signal.
scrolltype
The value of the gtk:scroll-type enumeration.
The signal is a keybinding signal which gets emitted to move the handle when the user is using key bindings to move it.
The "toggle-handle-focus" signal
lambda (widget)    :action      
widget
The gtk:paned widget that received the signal.
The signal is a keybinding signal which gets emitted to accept the current position of the handle and then move focus to the next widget in the focus chain. The default binding is the Tab key.
See also:
2024-4-22
Accessor gtk:paned-end-child (object)
Syntax:
(gtk:paned-end-child object) => child
(setf (gtk:paned-end-child) object) child)
Arguments:
object -- a gtk:paned widget
child -- a gtk:widget second child widget
Details:
Accessor of the end-child slot of the gtk:paned class. The gtk:paned-end-child function retrieves the end child widget of the given paned. The (setf gtk:paned-end-child) function sets the end child widget.
See also:
2024-4-22
Accessor gtk:paned-max-position (object)
Syntax:
(gtk:paned-max-position object) => position
Arguments:
object -- a gtk:paned widget
position -- an integer with the largest possible position
Details:
Accessor of the max-position slot of the gtk:paned class. The gtk:paned-max-position function gets the largest possible value for the position property.
See also:
2024-4-22
Accessor gtk:paned-min-position (object)
Syntax:
(gtk:paned-min-position object) => position
Arguments:
object -- a gtk:paned widget
position -- an integer with the smallest possible position
Details:
Accessor of the min-position slot of the gtk:paned class. The gtk:paned-min-position function gets the smallest possible value for the position property.
See also:
2024-4-22
Accessor gtk:paned-position (object)
Syntax:
(gtk:paned-position object) => position
(setf (gtk:paned-position position) position)
Arguments:
object -- a gtk:paned widget
position -- an integer with the pixel position of divider, a negative value means that the position is unset
Details:
Accessor of the position slot of the gtk:paned class. The gtk:paned-position function obtains the position of the divider between the two panes. The (setf gtk:paned-position) function sets the position.
See also:
2024-4-22
Accessor gtk:paned-position-set (object)
Syntax:
(gtk:paned-position-set object) => setting
(setf (gtk:paned-position-set position) setting)
Arguments:
object -- a gtk:paned widget
setting -- a boolean whether the position property should be used
Details:
Accessor of the position-set slot of the gtk:paned class. The gtk:paned-position-set function gets whether the position property should be used. The (setf gtk:paned-position-set) function sets whether the property should be used.
See also:
2024-4-22
Accessor gtk:paned-resize-end-child (object)
Syntax:
(gtk:paned-resize-end-child object) => resize
(setf (gtk:paned-resize-end-child) object) resize)
Arguments:
object -- a gtk:paned widget
resize -- a boolean whether the second child expands and shrinks
Details:
Accessor of the resize-end-child slot of the gtk:paned class. The gtk:paned-resize-end-child function returns whether the end child widget can be resized. The (setf gtk:paned-resize-end-child) function sets the property.
See also:
2024-4-22
Accessor gtk:paned-resize-start-child (object)
Syntax:
(gtk:paned-resize-start-child object) => resize
(setf (gtk:paned-resize-start-child) object) resize)
Arguments:
object -- a gtk:paned widget
resize -- a boolean whether the first child expands and shrinks
Details:
Accessor of the resize-start-child slot of the gtk:paned class. The gtk:paned-resize-start-child function returns whether the first child widget can be resized. The (setf gtk:paned-resize-start-child) function sets the property.
See also:
2024-4-22
Accessor gtk:paned-shrink-end-child (object)
Syntax:
(gtk:paned-shrink-end-child object) => shrink
(setf (gtk:paned-shrink-end-child) object) shrink)
Arguments:
object -- a gtk:paned widget
shrink -- a boolean whether the second child can be made smaller than its requisition
Details:
Accessor of the shrink-end-child slot of the gtk:paned class. The gtk:paned-shrink-end-child function returns whether the second child widget can be made smaller than its requisition. The (setf gtk:paned-shrink-end-child) function sets the property.
See also:
2024-4-22
Accessor gtk:paned-shrink-start-child (object)
Syntax:
(gtk:paned-shrink-start-child object) => shrink
(setf (gtk:paned-shrink-start-child) object) shrink)
Arguments:
object -- a gtk:paned widget
shrink -- a boolean whether the first child can be made smaller than its requisition
Details:
Accessor of the shrink-start-child slot of the gtk:paned class. The gtk:paned-shrink-start-child function returns whether the first child widget can be made smaller than its requisition. The (setf gtk:paned-shrink-start-child) function sets the property.
See also:
2024-4-22
Accessor gtk:paned-start-child (object)
Syntax:
(gtk:paned-start-child object) => child
(setf (gtk:paned-start-child) object) child)
Arguments:
object -- a gtk:paned widget
child -- a gtk:widget first child widget
Details:
Accessor of the start-child slot of the gtk:paned class. The gtk:paned-start-child function retrieves the start child widget of the given paned. The (setf gtk:paned-start-child) function sets the start child widget.
See also:
2024-4-22
Accessor gtk:paned-wide-handle (object)
Syntax:
(gtk:paned-wide-handle object) => wide
(setf (gtk:paned-wide-handle object) wide)
Arguments:
object -- a gtk:paned widget
wide -- a boolean with the value of the wide-handle property
Details:
Accessor of the wide-handle slot of the gtk:paned class. The gtk:paned-wide-handle function gets the wide-handle property. The (setf gtk:paned-wide-handle) function sets the property.
See also:
2024-4-22
Function gtk:paned-new (&optional orientation)
Arguments:
orientation -- a gtk:orientation value for the orientation of the paned widget, or the optional :horizontal value
Returns:
The new gtk:paned widget.
Details:
Creates a new paned widget.
See also:
2024-10-3

GtkNotebook

GEnum gtk:notebook-tab
Declaration:
(gobject:define-genum "GtkNotebookTab" notebook-tab
  (:export t
   :type-initializer "gtk_notebook_tab_get_type")
  (:tab-first 0)
  (:tab-last 1))  
Values:
:tab-first
The first tab in the notebook.
:tab-last
The last tab in the notebook.
Details:
The values of this enumeration are used in the action signals of the gtk:notebook widget.
See also:
2024-10-4
Class gtk:notebook-page
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write / Construct only)
The child widget for the notebook page.
detachable
The detachable property of type :boolean (Read / Write)
Whether the notebook tab is detachable.
Default value: false
menu
The menu property of type gtk:widget (Read / Write / Construct only)
The label displayed in the menu entry of the child widget.
menu-label
The menu-label property of type :string (Read / Write)
The text of the menu widget.
Default value: nil
position
The position property of type :int (Read / Write)
The index of the child widget in the parent.
Allowed values: >= -1
Default value: 0
reorderable
The reorderable property of type :boolean (Read / Write)
Whether the notebook tab is reorderable by user action.
Default value: false
tab
The tab property of type gtk:widget (Read / Write / Construct only)
The notebook tab for the notebook page.
tab-expand
The tab-expand property of type :boolean (Read / Write)
Whether to expand the notebook tab of the child widget.
Default value: false
tab-fill
The tab-fill property of type :boolean (Read / Write)
Whether the notebook tab of the child widget should fill the allocated area.
Default value: true
tab-label
The tab-label property of type :string (Read / Write)
The text of the notbook tab.
Default value: nil
Slot Access Functions:
Details:
The gtk:notebook-page object is an auxiliary object used by the gtk:notebook widget.
See also:
2024-10-4
Accessor gtk:notebook-page-child (object)
Syntax:
(gtk:notebook-page-child object) => child
(setf (gtk:notebook-page-child object) child)
Arguments:
object -- a gtk:notebook-page object
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:notebook-page class. The child widget for the notebook page.
See also:
2024-10-4
Accessor gtk:notebook-page-detachable (object)
Syntax:
(gtk:notebook-page-detachable object) => detachable
(setf (gtk:notebook-page-detachable object) detachable)
Arguments:
object -- a gtk:notebook-page object
detachable -- a boolean whether the tab is detachable
Details:
Accessor of the detachable slot of the gtk:notebook-page class. Whether the notebook tab is detachable.
See also:
2024-10-4
Accessor gtk:notebook-page-menu (object)
Syntax:
(gtk:notebook-page-menu object) => menu
(setf (gtk:notebook-page-menu object) menu)
Arguments:
object -- a gtk:notebook-page object
menu -- a gtk:widget object displayed in the menu entry of the child widget
Details:
Accessor of the menu slot of the gtk:notebook-page class. The label displayed in the menu entry of the child widget.
See also:
2024-10-4
Accessor gtk:notebook-page-menu-label (object)
Syntax:
(gtk:notebook-page-menu-label object) => label
(setf (gtk:notebook-page-menu-label object) label)
Arguments:
object -- a gtk:notebook-page object
label -- a string with the text of the menu widget
Details:
Accessor of the menu-label slot of the gtk:notebook-page class. The text of the menu widget.
See also:
2024-10-4
Accessor gtk:notebook-page-position (object)
Syntax:
(gtk:notebook-page-position object) => position
(setf (gtk:notebook-page-position object) position)
Arguments:
object -- a gtk:notebook-page object
position -- an integer with the index of the child widget in the parent
Details:
Accessor of the position slot of the gtk:notebook-page class. The index of the child widget in the parent.
See also:
2024-10-4
Accessor gtk:notebook-page-reorderable (object)
Syntax:
(gtk:notebook-page-reorderable object) => reorderable
(setf (gtk:notebook-page-reorderable object) reorderable)
Arguments:
object -- a gtk:notebook-page object
reorderable -- a boolean whether the notebook tab is reorderable
Details:
Accessor of the reorderable slot of the gtk:notebook-page class. Whether the notebook tab is reorderable by user action.
See also:
2024-10-4
Accessor gtk:notebook-page-tab (object)
Syntax:
(gtk:notebook-page-tab object) => tab
(setf (gtk:notebook-page-tab object) tab)
Arguments:
object -- a gtk:notebook-page object
tab -- a gtk:widget tab widget for the notebook page
Details:
Accessor of the tab slot of the gtk:notebook-page class. The notebook tab for the notebook page.
See also:
2024-10-4
Accessor gtk:notebook-page-tab-expand (object)
Syntax:
(gtk:notebook-page-tab-expand object) => expand
(setf (gtk:notebook-page-tab-expand object) expand)
Arguments:
object -- a gtk:notebook-page object
expand -- a boolean whether to expand the notebook tab of the child widget
Details:
Accessor of the tab-expand slot of the gtk:notebook-page class. Whether to expand the notebook tab of the child widget.
See also:
2024-10-4
Accessor gtk:notebook-page-tab-fill (object)
Syntax:
(gtk:notebook-page-tab-fill object) => fill
(setf (gtk:notebook-page-tab-fill object) fill)
Arguments:
object -- a gtk:notebook-page object
fill -- a boolean whether to expand the tab of the child widget
Details:
Accessor of the tab-fill slot of the gtk:notebook-page class. Whether to expand the notebook tab of the child widget.
See also:
2024-10-4
Accessor gtk:notebook-page-tab-label (object)
Syntax:
(gtk:notebook-page-tab-label object) => label
(setf (gtk:notebook-page-tab-label object) label)
Arguments:
object -- a gtk:notebook-page object
label -- a string with the text of the tab widget
Details:
Accessor of the tab-label slot of the gtk:notebook-page class. The text of the notebook tab.
See also:
2024-10-4
Class gtk:notebook-pages
Superclasses:
gtk:selection-model, gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:notebook-pages class holds a g:list-model object for the pages of a notebook. The gtk:notebook-pages function returns the list model for the pages. This object is not exported from the C library.
See also:
2024-11-10
Class gtk:notebook
Superclasses:
Documented Subclasses:
None
Direct Slots:
enable-popup
The enable-popup property of type :boolean (Read / Write)
If true, pressing the right mouse button on the notebook pops up a menu that you can use to go to a page.
Default value: false
group-name
The group-name property of type :string (Read / Write)
The group name for drag and drop operations of the notebook tab.
Default value: nil
page
The page property of type :int (Read / Write)
The index of the current page.
Allowed values: >= -1
Default value: -1
pages
The pages property of type g:list-model (Read)
The pages of the notebook.
scrollable
The scrollable property of type :boolean (Read / Write)
If true, scroll arrows are added if there are too many notebook tabs to fit.
Default value: false
show-border
The show-border property of type :boolean (Read / Write)
Whether the border should be shown.
Default value: true
show-tabs
The show-tabs property of type :boolean (Read / Write)
Whether tabs should be shown.
Default value: true
tab-pos
The tab-pos property of type gtk:position-type (Read / Write)
Which side of the notebook holds the notebook tabs.
Default value: :top
Returned by:
Slot Access Functions:
Details:
The gtk:notebook widget is a layout container whose children are pages that can be switched between using notebook tab labels along one edge.

Figure: GtkNotebook

There are many configuration options for gtk:notebook widgets. Among other things, you can choose on which edge the notebook tabs appear, see the gtk:notebook-tab-pos function, whether, if there are too many notebook tabs to fit the notebook should be made bigger or scrolling arrows added, see the gtk:notebook-scrollable function, and whether there will be a popup menu allowing the users to switch pages, see the gtk:notebook-popup-enable function.
GtkNotebook as GtkBuildable:
The gtk:notebook implementation of the gtk:buildable interface supports placing children into notebook tabs by specifying "tab" as the "type" attribute of a <child> element. Note that the content of the notebook tab must be created before the notebook tab can be filled. A notebook tab child can be specified without specifying a <child> type attribute. To add a child widget in the notebooks action area, specify "action-start" or "action-end" as the "type" attribute of the <child> element.

Example: A UI definition fragment with the gtk:notebook widget
<object class="GtkNotebook">
  <child>
    <object class="GtkLabel" id="notebook-content">
      <property name="label">Content</property>
    </object>
  </child>
  <child type="tab">
    <object class="GtkLabel" id="notebook-tab">
      <property name="label">Tab</property>
    </object>
  </child>
</object>    
CSS nodes:
notebook
├── header.top
│   ├── [<action widget>]
│   ├── tabs
│   │   ├── [arrow]
│   │   ├── tab
│   │   │   ╰── <tab label>
│   │   │
│   │   ├── tab[.reorderable-page]
│   │   │   ╰── <tab label>
│   │   ╰── [arrow]
│   ╰── [<action widget>]
│
╰── stack
    ├── <child>
    │
    ╰── <child>    
The gtk:notebook implementation has a main CSS node with name notebook, a subnode with name header and below that a subnode with name tabs which contains one subnode per notebook tab with name tab. If action widgets are present, their CSS nodes are placed next to the notebook tabs node. If the notebook is scrollable, CSS nodes with name arrow are placed as first and last child of the notebook tabs node. The main node gets the .frame style class when the notebook has a border, see the gtk:notebook-show-border function. The header node gets one of the .top, .bottom, .left or .right style classes, depending on where the notebook tabs are placed. For reorderable pages, the notebook tab node gets the .reorderable-page style class. A notebook tab node gets the .dnd style class while it is moved with drag and drop. The nodes are always arranged from left-to-right, regardless of text direction.
Accessibility:
The gtk:notebook implementation uses the following roles:
  • The :group role for the notebook widget.
  • The :tab-list role for the list of notebook tabs.
  • The :tab role for each notebook tab.
  • The :tab-panel role for each page.
Signal Details:
The "change-current-page" signal
lambda (notebook page)    :action      
notebook
The gtk:notebook widget emitting the signal.
page
The integer with the page index.
Returns
Whether the page was changed.
Emitted when the current page should be changed. The default bindings for this signal are the Ctrl+Alt+PgUp, Ctrl+Alt+PgDn, Ctrl+PgUp and Ctrl+PgDn keys.
The "create-window" signal
lambda (notebook page)    :run-last      
notebook
The gtk:notebook widget emitting the signal.
page
The gtk:widget object for the notebook tab of notebook that is being detached.
Returns
The gtk:notebook widget that page should be added to, or nil.
The signal is emitted when a detachable notebook tab is dropped on the root window. A handler for this signal can create a window containing a notebook where the notebook tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook, for example, the group-name property.
The "focus-tab" signal
lambda (notebook tab)    :action      
notebook
The gtk:notebook widget emitting the signal.
tab
The value of the gtk:notebook-tab enumeration.
Returns
Whether the notebook tab has been focused.
Emitted when a tab should be focused.
The "move-focus-out" signal
lambda (notebook direction)    :action      
notebook
The gtk:notebook widget emitting the signal.
direction
The gtk:direction-type value with the direction to move the focus.
Emitted when focus was moved out. The default bindings for this signal are the Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+←, Ctrl+→, Ctrl+↑ and Ctrl+↓.
The "page-added" signal
lambda (notebook child num)    :run-last      
notebook
The gtk:notebook widget emitting the signal.
child
The gtk:widget child page affected.
num
The unsigned integer with the child page number.
The signal is emitted in the notebook right after a page is added to the notebook.
The "page-removed" signal
lambda (notebook child num)   :run-last      
notebook
The gtk:notebook widget emitting the signal.
child
The gtk:widget child page affected.
num
The unsigned integer with the child page number.
The signal is emitted in the notebook right after a page is removed from the notebook.
The "page-reordered" signal
lambda (notebook child num)    :run-last      
notebook
The gtk:notebook widget emitting the signal.
child
The gtk:widget child page affected.
num
The unsigned integer with the child page number.
The signal is emitted in the notebook right after a page has been reordered.
The "reorder-tab" signal
lambda (notebook direction move-to-last)   :action      
notebook
The gtk:notebook widget emitting the signal.
direction
The value of the gtk:direction-type enumeration.
move-to-last
Whether to move to the last position.
Returns
Whether the notebook tab was moved.
Emitted when the notebook tab should be reordered. The default bindings for this signal are the Alt+Home, Alt+End, Alt+PgUp, Alt+PgDn, Alt+←, Alt+→, Alt+↑ and Alt+↓ keys.
The "select-page" signal
lambda (notebook move-focus)    :action      
notebook
The gtk:notebook widget emitting the signal.
move-focus
Whether to move focus.
Returns
Whether the page was selected.
Emitted when a page should be selected. The default binding for this signal is the key.
The "switch-page" signal
lambda (notebook page num)    :run-last      
notebook
The gtk:notebook widget emitting the signal.
page
The gtk:widget current page.
num
The unsigned integer with the index of the page.
Emitted when the user or a function changes the current page.
2024-10-4
Accessor gtk:notebook-enable-popup (object)
Syntax:
(gtk:notebook-enable-popup object) => enable
(setf (gtk:notebook-enable-popup object) enable)
Arguments:
object -- a gtk:notebook widget
enable -- if true, pops up a menu
Details:
Accessor of the enable-popup slot of the gtk:notebook class. If true, pressing the right mouse button on the notebook pops up a menu that you can use to go to a page.
See also:
2024-10-4
Accessor gtk:notebook-group-name (object)
Syntax:
(gtk:notebook-group-name object) => name
(setf (gtk:notebook-group-name object) name)
Arguments:
object -- a gtk:notebook widget
name -- a string with the group name of the notebook group, or nil to unset it
Details:
Accessor of the group-name slot of the gtk:notebook class. The gtk:notebook-group-name function gets the current group name for the notebook. The (setf gtk:notebook-group-name) function sets a group name.

Notebooks with the same group name will be able to exchange notebook tabs via drag and drop. A notebook with a nil group name will not be able to exchange notebook tabs with any other notebook.
See also:
2024-10-4
Accessor gtk:notebook-page (object)
Syntax:
(gtk:notebook-page object) => page
(setf (gtk:notebook-page object) page)
Arguments:
object -- a gtk:notebook widget
page -- an integer with the index of the current page
Details:
Accessor of the page slot of the gtk:notebook class. The index of the current page.
See also:
2024-10-4
Accessor gtk:notebook-pages (object)
Syntax:
(gtk:notebook-pages object) => pages
Arguments:
object -- a gtk:notebook widget
pages -- a g:list-model object with the pages of the notebook
Details:
Accessor of the pages slot of the gtk:notebook class. The gtk:notebook-pages function returns a g:list-model object that contains the pages of the notebook, and can be used to keep an up-to-date view.
See also:
2024-10-4
Accessor gtk:notebook-scrollable (object)
Syntax:
(gtk:notebook-scrollable object) => scrollable
(setf (gtk:notebook-scrollable object) scrollable)
Arguments:
object -- a gtk:notebook widget
scrollable -- true if scroll arrows should be added
Details:
Accessor of the scrollable slot of the gtk:notebook class. The gtk:notebook-scrollable function returns whether the notebook tab label area has arrows for scrolling if there are too many notebook tabs to fit in the area. The (setf gtk:notebook-scrollable) function sets whether the notebook tab label area will have arrows for scrolling.
See also:
2024-10-4
Accessor gtk:notebook-show-border (object)
Syntax:
(gtk:notebook-show-border object) => show-border
(setf (gtk:notebook-show-border object) show-border)
Arguments:
notebook -- a gtk:notebook widget
show-border -- true if a bevel should be drawn around the notebook
Details:
Accessor of the show-border slot of the gtk:notebook class. The gtk:notebook-show-border function returns whether a bevel will be drawn around the notebook pages. The (setf gtk:notebook-show-border) function sets whether a bevel will be drawn.

This only has a visual effect when the notebook tabs are not shown. See the gtk:notebook-show-tabs function.
See also:
2024-10-4
Accessor gtk:notebook-show-tabs (object)
Syntax:
(gtk:notebook-show-tabs object) => show-tabs
(setf (gtk:notebook-show-tabs object) show-tabs)
Arguments:
object -- a gtk:notebook widget
show-tabs -- true if the tabs should be shown
Details:
Accessor of the show-tabs slot of the gtk:notebook class. The gtk:notebook-show-tabs function returns whether the notebook tabs of the notebook are shown. The (setf gtk:notebook-show-tabs) function sets whether to show the notebook tabs.
See also:
2024-10-4
Accessor gtk:notebook-tab-pos (object)
Syntax:
(gtk:notebook-tab-pos object) => pos
(setf (gtk:notebook-tab-pos object) pos)
Arguments:
object -- a gtk:notebook widget
pos -- a value of the gtk:position-type enumeration with the edge to draw the notebook tabs at
Details:
Accessor of the tab-pos slot of the gtk:notebook class. The gtk:notebook-tab-pos function gets the edge at which the notebook tabs for switching pages in the notebook are drawn. The (setf gtk:notebook-tab-pos) function sets the edge.
See also:
2024-10-4
Function gtk:notebook-new ()
Returns:
The newly created gtk:notebook widget.
Details:
Creates a new notebook with no pages.
See also:
2024-10-4
Function gtk:notebook-n-pages (notebook)
Arguments:
notebook -- a gtk:notebook widget
Returns:
The integer with the number of pages in the notebook.
Details:
Gets the number of pages in a notebook.
See also:
2024-10-4
Function gtk:notebook-nth-page (notebook num)
Arguments:
notebook -- a gtk:notebook widget
num -- an integer with the index of a page in the notebook, or -1 to get the last page
Returns:
The gtk:widget child page, or nil if num is out of bounds.
Details:
Returns the child widget contained in page number num.
See also:
2024-10-4
Function gtk:notebook-page-num (notebook child)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child
Returns:
The index of the page containing child, or -1 if child is not in the notebook.
Details:
Finds the index of the page which contains the given child widget.
See also:
2024-10-4
Function gtk:notebook-current-page (notebook)
Syntax:
(gtk:notebook-current-page notebook) => num
(setf (gtk:notebook-current-page notebook) num)
Arguments:
notebook -- a gtk:notebook widget
num -- an integer with the index of the page to switch to, starting from 0, if negative, the last page will be used, if greater than the number of pages in the notebook, nothing will be done
Details:
The gtk:notebook-current-page function returns an integer with the index starting from 0 of the page number of the current page. The (setf gtk:notebook-current-page) function switches to the given page number.

Note that due to historical reasons, the gtk:notebook widget refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook.
See also:
2024-10-4
Function gtk:notebook-next-page (notebook)
Arguments:
notebook -- a gtk:notebook widget
Details:
Switches to the next page. Nothing happens if the current page is the last page.
See also:
2024-10-4
Function gtk:notebook-prev-page (notebook)
Arguments:
notebook -- a gtk:notebook widget
Details:
Switches to the previous page. Nothing happens if the current page is the first page.
See also:
2024-10-4
Function gtk:notebook-add-page (notebook child tab &key pos menu)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child widget to use as the content of the page
tab -- a gtk:widget object to use as the label for the page, or nil to use the default label, 'page N'
pos -- an integer with the index starting at 0 at which to insert the page, or -1 to append the page after all other pages, or :end to append the page, :start to prepend the page, the default value is :end
menu -- a gtk:widget object to use as a label for the page-switch menu, if that is enabled
Returns:
The integer with the index starting from 0 of the added page in the notebook, or -1 if the function fails.
Details:
Inserts a page into the notebook depending on the value of the pos keyword argument with the :end default value:
:start
Prepends a page to the notebook. This replaces the functions:
  • gtk_notebook_prepend_page()
  • gtk_notebook_prepend_page_menu()
:end
Appends a page to the notebook. This replaces the functions:
  • gtk_notebook_append_page()
  • gtk_notebook_append_page_menu()
otherwise
Insert a page into the notebook at the given pos, which is an integer with the index starting from 0. This replaces the functions:
  • gtk_notebook_insert_page()
  • gtk_notebook_insert_page_menu()
If the menu optinal argument is nil, that is the default value, and the tab argument is a gtk:label widget or nil, then the menu label will be a newly created label with the same text as tab. If the tab argument is not a gtk:label widget, the menu argument must be specified if the page-switch menu is to be used.
See also:
2024-10-4
Function gtk:notebook-remove-page (notebook page)
Arguments:
notebook -- a gtk:notebook widget
page -- an integer with the index of a notebook page, starting from 0, if -1, the last page will be removed, or the gtk:widget child page
Details:
Removes a page from the notebook given the page widget or its index in the notebook.
Notes:
In the Lisp implementation the argument can be an integer for the index or the page widget. The index of the page widget is got with the function gtk:notebook-page-num and passed to the C function.
Examples:
(defvar notebook (make-instance 'gtk:notebook))
=> NOTEBOOK
(defvar page (make-instance 'gtk:frame))
=> PAGE
(gtk:notebook-append-page notebook page nil)
=> 0
(gtk:notebook-remove-page notebook page)
(gtk:notebook-append-page notebook page nil)
=> 0
(gtk:notebook-remove-page notebook 0)    
See also:
2024-10-4
Function gtk:notebook-detach-tab (notebook page)
Arguments:
notebook -- a gtk:notebook widget
page -- a gtk:widget child page, or an integer with the index of a notebook page
Details:
Removes the child page from the notebook. This function is very similar to the gtk:notebook-remove-page function, but additionally informs the notebook that the removal is happening as part of a drag and drop operation of the notebook tab, which should not be cancelled.
See also:
2024-10-4
Function gtk:notebook-reorder-child (notebook child pos)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child page to move
pos -- an integer with the position, or -1 to move to the end
Details:
Reorders the page containing the child, so that it appears in the given position. If the position is greater than or equal to the number of children in the list or negative, the child will be moved to the end of the list.
See also:
2024-10-4
Function gtk:notebook-popup-enable (notebook)
Arguments:
notebook -- a gtk:notebook widget
Details:
Enables the popup menu. If the user clicks with the right mouse button on the notebook tab labels, a menu with all the pages will be popped up.
Notes:
This function calls the gtk:notebook-enable-popup function with the true value.
See also:
2024-10-4
Function gtk:notebook-popup-disable (notebook)
Arguments:
notebook -- a gtk:notebook widget
Details:
Disables the popup menu. See the gtk:notebook-popup-enable function.
Notes:
This function calls the gtk:notebook-enable-popup function with the false value.
See also:
2024-10-4
Function gtk:notebook-tab-detachable (notebook child)
Syntax:
(gtk:notebook-tab-detachable notebook child) => detachable
(setf (gtk:notebook-tab-detachable notebook child) detachable)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child page
detachable -- a boolean whether the notbook tab is detachable or not
Details:
The gtk:notebook-tab-detachable function returns whether the notbook tab content can be detached from the notebook to another notebook or widget. The (setf gtk:notebook-tab-detachable) function sets whether the notebook tab can be detached.

Note that two notebooks must share a common group identifier, see the gtk:notebook-group-name function, to allow automatic notebook tabs interchange between them.

If you want a widget to interact with a notebook through DnD, that is, accept dragged notebook tabs from it, it must be set as a drop destination by adding to it a gtk:drop-target controller that accepts the GType "GtkNotebookPage". The :value value of said drop target will be preloaded with a gtk:notebook-page object that corresponds to the dropped notebook tab, so you can process the value via "accept" or "drop" signals.

Note that you should use the gtk:notebook-detach-tab function instead of the gtk:notebook-remove-page function if you want to remove the notebook tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation.

If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it.
Examples:
static void
on_drag_data_received (GtkWidget        *widget,
                       GdkDrop          *drop,
                       GtkSelectionData *data,
                       guint             time,
                       gpointer          user_data)
{
  GtkDrag *drag;
  GtkWidget *notebook;
  GtkWidget **child;

drag = gtk_drop_get_drag (drop); notebook = g_object_get_data (drag, "gtk-notebook-drag-origin"); child = (void*) gtk_selection_data_get_data (data);

// process_widget (*child);

gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); }
See also:
2024-10-4
Function gtk:notebook-tab-reorderable (notebook child)
Syntax:
(gtk:notebook-tab-reorderable notebook child) => reorderable
(setf (gtk:notebook-tab-reorderable notebook child) reorderable)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child page
reorderable -- a boolean whether the notebook tab is reorderable or not
Details:
The gtk:notebook-tab-reorderable function gets whether the notebook tab can be reordered via drag and drop or not. The (setf gtk:notebook-tab-reorderable) function sets whether the notebook tab can be reordered.
See also:
2024-10-4
Function gtk:notebook-menu-label (notebook child)
Syntax:
(gtk:notebook-menu-label notebook child) => menu
(setf (gtk:notebook-menu-label notebook child) menu)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child contained in a page of the notebook
menu -- a gtk:widget menu label, or nil for default
Details:
The gtk:notebook-menu-label function returns the menu label, or nil if the notebook page does not have a menu label other than the default notebook tab label. The (setf gtk:notebook-menu-label) function changes the menu label for the page containing the child.
See also:
2024-10-4
Function gtk:notebook-menu-label-text (notebook child)
Syntax:
(gtk:notebook-menu-label-text notebook child) => text
(setf (gtk:notebook-menu-label-text notebook child) text)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child of a page of the notebook
text -- a string with the label text
Details:
The gtk:notebook-menu-label-text function retrieves the text of the menu label for the page containing child. The (setf gtk:notebook-menu-label-text) function creates a new label and sets it as the menu label of the child page.
See also:
2024-10-4
Function gtk:notebook-tab-label (notebook child)
Syntax:
(gtk:notebook-tab-label notebook child) => tab
(setf (gtk:notebook-tab-label notebook child) tab)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child page
tab -- a gtk:widget object for the notebook tab label to use, or nil for default notebook tab label
Details:
The gtk:notebook-tab-label function returns the notebook tab label for the page child. The nil value is returned if the child is not in the notebook or if no notebook tab label has been set for the child. The (setf gtk:notebook-tab-label) function changes the notebbok tab label for the child page. If the nil value is specified for tab, then the page will have the label 'page N'.
See also:
2024-10-4
Function gtk:notebook-tab-label-text (notebook child)
Syntax:
(gtk:notebook-tab-label-text notebook child) => text
(setf (gtk:notebook-tab-label-text notebook child) text)
Arguments:
notebook -- a gtk:notebook widget
child -- a gtk:widget child contained in a page of the notebook
text -- a string with the label text
Details:
The gtk:notebook-tab-label-text function retrieves the text of the notebook tab label for the page containing child. The (setf gtk:notebook-tab-label-text) function creates a new label and sets it as the notebook tab label for the page containing child.
See also:
2024-10-4
Function gtk:notebook-action-widget (notebook packtype)
Syntax:
(gtk:notebook-action-widget notebook packtype) => widget
(setf (gtk:notebook-action-widget notebook packtype) widget)
Arguments:
notebook -- a gtk:notebook widget
packtype -- a gtk:pack-type value for the action
widget -- a gtk:widget object
Details:
The gtk:notebook-action-widget function gets one of the action widgets. The (setf gtk:notebook-action-widget) function sets the widget as one of the action widgets. Depending on the pack type the widget will be placed before or after the notebook tabs. You can use a gtk:box widget if you need to pack more than one widget on the same side.
See also:
2024-10-4

GtkExpander

Class gtk:expander
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
expanded
The expanded property of type :boolean (Read / Write / Construct)
Whether the expander has been opened to reveal the child widget.
Default value: false
label
The label property of type :string (Read / Write / Construct)
Text of the label of the expander.
Default value: nil
label-widget
The label-widget property of type gtk:widget (Read / Write)
A widget to display in place of the usual expander label.
resize-toplevel
The resize-toplevel property of type :boolean (Read / Write)
When this property is true, the expander will resize the toplevel widget containing the expander upon expanding and collapsing.
Default value: false
use-markup
The use-markup property of type :boolean (Read / Write / Construct)
The text of the label includes XML Pango markup.
Default value: false
use-underline
The use-underline property of type :boolean (Read / Write / Construct)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:expander widget allows the user to hide or show its child by clicking on an expander triangle.

Figure: GtkExpander

Normally you use an expander as you would use a frame. You create the child widget and use the gtk:expander-child function to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically.

Special Usage
There are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a gtk:expander widget but do not add a child widget to it. The expander widget has an expanded property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows:
(let ((expander (gtk:expander-new-with-mnemonic "_More Options")))
  (g:signal-connect expander "notify::expanded"
                    (lambda (object param)
                      (if (gtk:expander-expanded object)
                          ;; Show or create widgets
                          ...
                          ;; Hide or destroy widgets
                          ... )))
  ... )  
GtkExpander as GtkBuildable:
The gtk:expander implementation of the gtk:buildable interface supports placing a child in the label position by specifying "label" as the "type" attribute of a <child> element. A normal content child can be specified without specifying a <child> type attribute.

Example: A UI definition fragment with a gtk:expander widget.
<object class="GtkExpander">
  <child type="label">
    <object class="GtkLabel" id="expander-label"/>
  </child>
  <child>
    <object class="GtkEntry" id="expander-content"/>
  </child>
</object>    
CSS nodes:
expander
├── title
│   ├── arrow
│   ╰── <label widget>
╰── <child>    
The gtk:expander implementation has three CSS nodes, the main node with the name expander, a subnode with name title and node below it with name arrow. The arrow of an expander that is showing its child gets the :checked pseudoclass added to it.
Accessibility:
The gtk:expander implementation uses the :button role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (expander)   :action      
expander
The gtk:expander widget which receives the signal.
Activates the expander.
2024-4-17
Accessor gtk:expander-child (object)
Syntax:
(gtk:expander-child object) => child
(setf (gtk:expander-child object) child)
Arguments:
object -- a gtk:expander widget
child -- a gtk:widget child widget of the expander
Details:
Accessor of the child slot of the gtk:expander class.
See also:
2023-8-23
Accessor gtk:expander-expanded (object)
Syntax:
(gtk:expander-expanded object) => expanded
(setf (gtk:expander-expanded object) expanded)
Arguments:
object -- a gtk:expander widget
expanded -- a boolean whether the child widget is revealed
Details:
Accessor of the expanded slot of the gtk:expander class. The gtk:expander-expanded function queries a gtk:expander widget and returns its current state. Set to true, if you want the child widget to be revealed, and false if you want the child widget to be hidden.
See also:
2023-8-23
Accessor gtk:expander-label (object)
Syntax:
(gtk:expander-label object) => label
(setf (gtk:expander-label object) label)
Arguments:
object -- a gtk:expander widget
label -- a string with the text of the label of the expander
Details:
Accessor of the label slot of the gtk:expander class. The gtk:expander-label function fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup, as set by the (setf gtk:expander-label) function.

If the label text has not been set the return value will be nil. This will be the case if you create an empty button with the gtk:button-new function to use as a container.
See also:
2023-8-23
Accessor gtk:expander-label-widget (object)
Syntax:
(gtk:expander-label-widget object) => widget
(setf (gtk:expander-label-widget object) widget)
Arguments:
object -- a gtk:expander widget
widget -- a gtk:widget label widget
Details:
Accessor of the label-widget slot of the gtk:expander class. The gtk:expander-label-widget function retrieves the label widget for the frame. The (setf gtk:expander-label-widget) function sets the label widget for the expander.

This is the widget that will appear embedded alongside the expander arrow.
See also:
2024-4-17
Accessor gtk:expander-resize-toplevel (object)
Syntax:
(gtk:expander-resize-toplevel object) => resize
(setf (gtk:expander-resize-toplevel object) resize)
Arguments:
object -- a gtk:expander widget
resize -- a boolean whether to resize the toplevel
Details:
Accessor of the resize-toplevel slot of the gtk:expander class. The gtk:expander-resize-toplevel function returns whether the expander will resize the toplevel widget containing the expander upon resizing and collpasing. The (setf gtk:expander-resize-toplevel) function sets whether the expander will resize.
See also:
2024-4-17
Accessor gtk:expander-use-markup (object)
Syntax:
(gtk:expander-use-markup object) => use-markup
(setf (gtk:expander-use-markup object) use-markup)
Arguments:
object -- a gtk:expander widget
use-markup -- true if the text of the label should be parsed for markup
Details:
Accessor of the use-markup slot of the gtk:expander class. The gtk:expander-use-markup function returns whether the text of the label is interpreted as marked up with the Pango text markup language. The (setf gtk:expander-use-markup) function sets whether the text of the label contains markup.
See also:
2023-8-23
Accessor gtk:expander-use-underline (object)
Syntax:
(gtk:expander-use-underline object) => use-underline
(setf (gtk:expander-use-underline object) use-underline)
Arguments:
object -- a gtk:expander widget
use-underline -- true if underlines in the text indicate mnemonics
Details:
Accessor of the use-underline slot of the gtk:expander class. The gtk:expander-use-underline function returns whether an embedded underline in the expander label indicates a mnemonic.

If true, an underline in the text of the expander label indicates the next character should be used for the mnemonic accelerator key.
See also:
2023-8-23
Function gtk:expander-new (label)
Arguments:
label -- a string with the text of the label
Returns:
The new gtk:expander widget.
Details:
Creates a new expander using label as the text of the label.
See also:
2024-4-17
Function gtk:expander-new-with-mnemonic (label)
Arguments:
label -- a string with the text of the label with an underscore in front of the mnemonic character
Returns:
The new gtk:expander widget.
Details:
Creates a new expander using label as the text of the label. If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use two underscores '__'. The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.
See also:
2024-4-17

GtkAspectFrame

Class gtk:aspect-frame
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
obey-child
The obey-child property of type :boolean (Read / Write)
Force aspect ratio to match that of the child widget of the aspect frame.
Default value: true
ratio
The ratio property of type :float (Read / Write)
Aspect ratio if the obey-child property is false.
Allowed values: [0.0001, 10000.0]
Default value: 1.0
xalign
The xalign property of type :float (Read / Write)
The x alignment of the child.
Allowed values: [0.0, 1.0]
Default value: 0.5
yalign
The yalign property of type :float (Read / Write)
The y alignment of the child.
Allowed values: [0.0, 1.0]
Default value: 0.5
Returned by:
Slot Access Functions:
Details:
The gtk:aspect-frame widget preserves the aspect ratio of its child. The frame can respect the aspect ratio of the child widget, or use its own aspect ratio.
CSS nodes:
The gtk:aspect-frame implementation uses a CSS node with name aspectframe.
Accessibility:
Until GTK 4.10, the gtk:aspect-frame implementation used the :group role. Starting from GTK 4.12, the gtk:aspect-frame implementation uses the :generic role.
See also:
2023-8-23
Accessor gtk:aspect-frame-child (object)
Syntax:
(gtk:aspect-frame-child object) => child
(setf (gtk:aspect-frame-child object) child)
Arguments:
object -- a gtk:aspect-frame widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:aspect-frame class.
See also:
2024-4-21
Accessor gtk:aspect-frame-obey-child (object)
Syntax:
(gtk:aspect-frame-obey-child object) => obey
(setf (gtk:aspect-frame-obey-child object) obey)
Arguments:
object -- a gtk:aspect-frame widget
obey -- a boolean whether to force the aspect ratio
Details:
Accessor of the obey-child slot of the gtk:aspect-frame class. Whether to force the aspect ratio to match that of the child widget of the aspect frame.
See also:
2024-4-21
Accessor gtk:aspect-frame-ratio (object)
Syntax:
(gtk:aspect-frame-ratio object) => ratio
(setf (gtk:aspect-frame-ratio object) ratio)
Arguments:
object -- a gtk:aspect-frame widget
ratio -- a float with an aspect ratio
Details:
Accessor of the ratio slot of the gtk:aspect-frame class. The aspect ratio if the obey-child property is false. Allowed values are in [0.0001, 10000.0]. The default value is 1.0.
See also:
2024-4-21
Accessor gtk:aspect-frame-xalign (object)
Syntax:
(gtk:aspect-frame-xalign object) => xalign
(setf (gtk:aspect-frame-xalign object) xalign)
Arguments:
object -- a gtk:aspect-frame widget
xalign -- a float with the x alignment of the child widget
Details:
Accessor of the xalign slot of the gtk:aspect-frame class. The x alignment of the child widget in the aspect frame container.
See also:
2024-4-21
Accessor gtk:aspect-frame-yalign (object)
Syntax:
(gtk:aspect-frame-yalign object) => yalign
(setf (gtk:aspect-frame-yalign object) yalign)
Arguments:
object -- a gtk:aspect-frame widget
yalign -- a float with the y alignment of the child widget
Details:
Accessor of the yalign slot of the gtk:aspect-frame class. The y alignment of the child widget in the aspect frame container.
See also:
2024-4-21
Function gtk:aspect-frame-new (xalign yalign ratio obey)
Arguments:
xalign -- a float with the horizontal alignment of the child within the allocation of the aspect frame, this ranges from 0.0 (left aligned) to 1.0 (right aligned)
yalign -- a float with the vertical alignment of the child within the allocation of the aspect frame, this ranges from 0.0 (left aligned) to 1.0 (right aligned)
ratio -- a float with the desired aspect ratio
obey -- if true, ratio is ignored, and the aspect ratio is taken from the requistion of the child
Returns:
The new gtk:aspect-frame widget.
Details:
Create a new aspect frame.
See also:
2024-4-21

GtkFixed

Class gtk:fixed
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:fixed widget is a container which can place child widgets at fixed positions and with fixed sizes, given in pixels. The fixed widget performs no automatic layout management.

For most applications, you should not use this container. It keeps you from having to learn about the other GTK containers, but it results in broken applications. With the gtk:fixed widget, the following things will result in truncated text, overlapping widgets, and other display bugs:
  • Themes, which may change widget sizes.
  • Fonts other than the one you used to write the application will of course change the size of widgets containing text. Keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts.
  • Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases.
In addition, the fixed widget cannot properly be mirrored in right-to-left languages such as Hebrew and Arabic. That is, normally GTK will order containers appropriately for the text direction, for example, to put labels to the right of the thing they label when using an RTL language, but it cannot do that with the gtk:fixed widget. So if you need to reorder widgets depending on the text direction, you would need to manually detect it and adjust child positions accordingly.

Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application.

If you know none of these things are an issue for your application, and prefer the simplicity of the gtk:fixed widget, by all means use the fixed widget. But you should be aware of the tradeoffs.
2025-3-25
Function gtk:fixed-new ()
Returns:
The new gtk:fixed widget.
Details:
Creates a new fixed widget.
See also:
2025-3-25
Function gtk:fixed-put (fixed child x y)
Arguments:
fixed -- a gtk:fixed widget
child -- a gtk:widget child widget to add
x -- a number coerced to a double float for the horizontal position to place the child widget at
y -- a number coerced to a double float for the vertical position to place the child widget at
Details:
Adds a child widget to a fixed widget and assigns a translation transformation to the given x and y coordinates to it.
See also:
2025-3-25
Function gtk:fixed-remove (fixed child)
Arguments:
fixed -- a gtk:fixed widget
child -- a gtk:widget child widget to remove
Details:
Removes a child widget from the fixed widget, after it has been added with the gtk:fixed-put function.
See also:
2025-3-25
Function gtk:fixed-move (fixed child x y)
Arguments:
fixed -- a gtk:fixed widget
child -- a gtk:widget child widget
x -- a number coerced to a double float for the horizontal position to move the child widget to
y -- a number coerced to a double float for the vertical position to move the child widget to
Details:
Sets a translation transformation to the given x and y coordinates to the child widget of the given fixed widget.
See also:
2025-3-25
Function gtk:fixed-child-position (fixed child)
Arguments:
fixed -- a gtk:fixed widget
child -- a gtk:widget child widget of fixed
Returns:
x -- a double float for the horizontal position of widget
y -- a double float for the vertical position of widget
Details:
Retrieves the translation transformation of the given child widget in the fixed container. See also the gtk:fixed-child-transform function.
See also:
2025-3-25
Function gtk:fixed-child-transform (fixed child)
Syntax:
(gtk:fixed-child-transform object) => transform
(setf (gtk:fixed-child-transform object) transform)
Arguments:
fixed -- a gtk:fixed widget
child -- a gtk:widget child widget of fixed
transform -- a gsk:transform instance for the transformation assigned to the child widget
Details:
The gtk:fixed-child-transform function retrieves the transformation for child. The (setf gtk:fixed-child-transform) function sets the transformation. This is a convenience function that retrieves the gtk:fixed-layout-child instance associated to child and calls the gtk:fixed-layout-child-transform function.
See also:
2025-3-25

Layout Managers

GtkLayoutManager

Class gtk:layout-manager
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Layout managers are delegate classes that handle the preferred size and the allocation of a container widget. You typically subclass the gtk:layout-manager class if you want to implement a layout policy for the children of a widget, or if you want to determine the size of a widget depending on its contents.

Each gtk:widget object can only have one gtk:layout-manager object associated to it at any given time. It is possible, though, to replace the layout manager object using the gtk:widget-layout-manager function.

Layout properties
A layout manager can expose properties for controlling the layout of each child, by creating an object type derived from the gtk:layout-child class and installing the properties on it as normal g:object properties.

Each gtk:layout-child object storing the layout properties for a specific child widget is created through the gtk:layout-manager-layout-child function. A layout manager controls the creation of its gtk:layout-child objects by overriding the GtkLayoutManagerClass.create_layout_child() virtual function. The typical implementation should look like:
static GtkLayoutChild *
create_layout_child (GtkLayoutManager *manager,
                     GtkWidget        *container,
                     GtkWidget        *child)
{
  return g_object_new (your_layout_child_get_type (),
                       "layout-manager", manager,
                       "child-widget", child,
                       NULL);
}  
The layout-manager and child-widget properties on the newly created gtk:layout-child object are mandatory. The gtk:layout-manager object will cache the newly created gtk:layout-child object until the widget is removed from its parent, or the parent removes the layout manager.

Each gtk:layout-manager object creating a gtk:layout-child object should use the gtk:layout-manager-layout-child function every time it needs to query the layout properties. Each gtk:layout-child object should call the gtk:layout-manager-layout-changed function every time a property is updated, in order to queue a new size measuring and allocation.
See also:
2024-10-14
Function gtk:layout-manager-measure (layout widget orientation size)
Arguments:
layout -- a gtk:layout-manager object
widget -- a gtk:widget object using layout
orientation -- a gtk:orientation value to measure
size -- an integer with the size for the opposite of orientation, for instance, if the orientation is :horizontal, this is the height of the widget, if the orientation is :vertical, this is the width of the widget, this allows to measure the height for the given width, and the width for the given height, use -1 if the size is not known
Returns:
minimum -- an integer with the minimum size for the given size and orientation
natual -- an integer with the natural, or preferred size for the given size and orientation
minimum-baseline -- an integer with the baseline position for the minimum size
natural-baseline -- an integer with the baseline position for the natural size
Details:
Measures the size of the widget using layout, for the given orientation and size. See the gtk:widget objects geometry management section for more details.
See also:
2024-4-12
Function gtk:layout-manager-allocate (layout widget width height baseline)
Arguments:
layout -- a gtk:layout-manager object
widget -- a gtk:widget object using layout
width -- an integer with the new width of the widget
height -- an integer with the new height of the widget
baseline -- an integer with the baseline position of the widget, or -1
Details:
This function assigns the given width, height, and baseline to a widget, and computes the position and sizes of the children of the widget using the layout management policy of layout.
See also:
2024-4-19
Function gtk:layout-manager-request-mode (layout)
Arguments:
layout -- a gtk:layout-manager object
Returns:
The gtk:size-request-mode value for layout.
Details:
Retrieves the request mode for the layout manager.
See also:
2024-10-14
Function gtk:layout-manager-widget (layout)
Arguments:
layout -- a gtk:layout-manager object
Returns:
The gtk:widget object for layout.
Details:
Retrieves the widget using the given layout manager.
See also:
2024-10-14
Function gtk:layout-manager-layout-child (layout child)
Arguments:
layout -- a gtk:layout-manager object
child -- a gtk:widget child widget
Returns:
The gtk:layout-child object for layout.
Details:
Retrieves a gtk:layout-child object for the gtk:layout-manager object, creating one if necessary. The child widget must be a child of the widget using the layout manager.

The gtk:layout-child object is owned by the gtk:layout-manager object, and is guaranteed to exist as long child is a child of the gtk:widget object using the given layout manager.
See also:
2024-10-14
Function gtk:layout-manager-layout-changed (layout)
Arguments:
layout -- a gtk:layout-manager object
Details:
Queues a resize on the gtk:widget object using layout, if any. This function should be called by subclasses of the gtk:layout-manager class in response to changes to their layout management policies.
See also:
#2024-10-14

GtkLayoutChild

Class gtk:layout-child
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
child-widget
The child-widget property of type gtk:widget (Read / Write / Construct only)
The widget that is associated to the gtk:layout-child object.
layout-manager
The layout-manager property of type gtk:layout-manager (Read / Write / Construct only)
The layout manager that created the gtk:layout-child object.
Details:
The gtk:layout-child class is the base class for objects that are meant to hold layout properties. If a gtk:layout-manager object has per-child properties, like their packing type, or the horizontal and vertical span, or the icon name, then the layout manager should use a gtk:layout-child implementation to store those properties.

A gtk:layout-child instance is only ever valid while a widget is part of a layout.
See also:
2024-4-19
Accessor gtk:layout-child-child-widget (object)
Syntax:
(gtk:layout-child-child-widget object) => child
Arguments:
object -- a gtk:layout-child object
child -- a gtk:widget object
Details:
Retrieves the gtk:widget child widget associated to the given object.
See also:
2024-4-19
Accessor gtk:layout-child-layout-manager (object)
Syntax:
(gtk:layout-child-layout-manager object) => manager
Arguments:
object -- a gtk:layout-child object
manager -- a gtk:layout-manager object
Details:
Retrieves the gtk:layout-manager object that created the given object.
See also:
2024-4-19

GtkBinLayout

Class gtk:bin-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:bin-layout class is a gtk:layout-manager subclass useful for create "bins" of widgets. The gtk:bin-layout object will stack each child of a widget on top of each other, using the hexpand, vexpand, halign, and valign properties of each child widget to determine where they should be positioned.
See also:
2024-4-19
Function gtk:bin-layout-new ()
Returns:
The newly created gtk:bin-layout object.
Details:
Creates a new gtk:bin-layout object.
See also:
2024-4-19

GtkBoxLayout

Class gtk:box-layout
Superclasses:
gtk:layout-manager, gtk:orientable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
baseline-child
The baseline-child property of type :int (Read / Write)
The child that determines the baseline of the box in vertical layout. If the child does baseline positioning, then its baseline is lined up with the baseline of the box. If it does not, then the bottom edge of the child is used. Since 4.12
Default value: -1
baseline-position
The baseline-position property of type gtk:baseline-position (Read / Write)
The position of the allocated baseline within the extra space allocated to each child of the widget using a box layout manager. This property is only relevant for horizontal layouts containing at least one child with a baseline alignment.
Default value: :center
homogeneous
The homogeneous property of type :boolean (Read / Write)
Whether the box layout should distribute the available space homogeneously among the children of the widget using it as a layout manager.
Default value: false
spacing
The spacing property of type :int (Read / Write)
The space between each child of the widget using the box layout as its layout manager.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:box-layout class is a layout manager that arranges the children of any widget using it into a single row or column. Whether it is a row or column depends on the value of its orientation property. Within the other dimension all children all allocated the same size. The gtk:box-layout object will respect the halign and valign properties of each child widget.

If you want all children to be assigned the same size, you can use the homogeneous property.

If you want to specify the amount of space placed between each child, you can use the spacing property.
See also:
2024-4-19
Accessor gtk:box-layout-baseline-position (object)
Syntax:
(gtk:box-layout-baseline-position object) => position
(setf (gtk:box-layout-baseline-position object) position)
Arguments:
object -- a gtk:box-layout object
position -- a gtk:baseline-position value
Details:
Accessor of the baseline-position slot of the gtk:box-layout class. The gtk:box-layout-baseline-position function gets the baseline position. The (setf gtk:box-layout-baseline-position) function sets the baseline position of a box layout.

The baseline position affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then the given position is used to allocate the baseline within the extra space available.
See also:
2024-4-19
Accessor gtk:box-layout-homogeneous (object)
Syntax:
(gtk:box-layout-homogeneous object) => homogeneous
(setf (gtk:box-layout-homogeneous object) homogeneous)
Arguments:
object -- a gtk:box-layout object
homogeneous -- true if the box layout is homogeneous
Details:
Accessor of the homogeneous slot of the gtk:box-layout class. The gtk:box-layout-homogeneous function returns whether the box layout will allocate the same size to all children. The (setf gtk:box-layout-homogeneous) function sets the property.
See also:
2024-4-19
Accessor gtk:box-layout-spacing (object)
Syntax:
(gtk:box-layout-spacing object) => spacing
(setf (gtk:box-layout-spacing object) spacing)
Arguments:
object -- a gtk:box-layout object
spacing -- an integer with the spacing of the box layout
Details:
Accessor of the spacing slot of the gtk:box-layout class. The gtk:box-layout-spacing function returns the space that the box layout puts between children. The (setf gtk:box-layout-spacing) function sets the spacing.
See also:
2024-4-19
Function gtk:box-layout-new (orientation)
Arguments:
orientation -- a gtk:orientation value
Returns:
The new gtk:box-layout object.
Details:
Creates a new box layout.
See also:
2024-4-19

GtkCenterLayout

Class gtk:center-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
shrink-center-last
The shrink-center-last property of type :boolean (Read / Write)
Whether to shrink the center widget after other children. By default, when there is no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to false, start and end widgets keep natural width and the center widget starts shrinking instead.
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:center-layout class is a layout manager that manages up to three children. The start widget is allocated at the start of the layout (left in LRT layouts and right in RTL ones), and the end widget at the end. The center widget is centered regarding the full width of the layout.
See also:
2024-4-19
Accessor gtk:center-layout-shrink-center-last (object)
Syntax:
(gtk:center-layout-shrink-center-last object) => setting
(setf (gtk:center-layout-shrink-center-last object) setting)
Arguments:
object -- a gtk:center-layout object
setting -- a boolean whether to shrink the center widget after others
Details:
Accessor of the shrink-center-last slot of the gtk:center-layout class. The gtk:center-layout-shrink-center-last function gets whether object shrinks the center widget after other children. The (setf gtk:center-layout-shrink-center-last) function sets whether to shrink the center widget after other children.

By default, when there is no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to false, start and end widgets keep natural width and the center widget starts shrinking instead.

Since 4.12
See also:
2024-4-19
Function gtk:center-layout-new ()
Returns:
The newly created gtk:center-layout object.
Details:
Creates a new center layout manager.
See also:
2024-4-19
Function gtk:center-layout-orientation (layout)
Syntax:
(gtk:center-layout-orientation layout) => orientation
(setf (gtk:center-layout-orientation layout) orientation)
Arguments:
layout -- a gtk:center-layout object
orientation -- a gtk:orientation value
Details:
The gtk:center-layout-orientation function gets the current orienration of the layout manager. The (setf gtk:center-layout-orientation) function sets the orientation.
See also:
2024-4-19
Function gtk:center-layout-baseline-position (layout)
Syntax:
(gtk:center-layout-baseline-position layout) => position
(setf (gtk:center-layout-baseline-position layout) position)
Arguments:
layout -- a gtk:center-layout object
position -- a gtk:baseline-position value
Details:
The gtk:center-layout-baseline-position function gets the current baseline position of the layout manager. The (setf gtk:center-layout-baseline-position) function sets the baseline-position.
See also:
2024-4-19
Function gtk:center-layout-start-widget (layout)
Syntax:
(gtk:center-layout-start-widget layout) => widget
(setf (gtk:center-layout-start-widget layout) widget)
Arguments:
layout -- a gtk:center-layout object
widget -- a gtk:widget start widget
Details:
The gtk:center-layout-start-widget function returns the start widget of the layout. The (setf gtk:center-layout-start-widget) function sets the start widget.
See also:
2024-4-19
Function gtk:center-layout-center-widget (layout)
Syntax:
(gtk:center-layout-center-widget layout) => widget
(setf (gtk:center-layout-center-widget layout) widget)
Arguments:
layout -- a gtk:center-layout object
widget -- a gtk:widget center widget
Details:
The gtk:center-layout-center-widget function returns the center widget of the layout. The (setf gtk:center-layout-center-widget) function sets the center widget.
See also:
2024-4-19
Function gtk:center-layout-end-widget (layout)
Syntax:
(gtk:center-layout-end-widget layout) => widget
(setf (gtk:center-layout-end-widget layout) widget)
Arguments:
layout -- a gtk:center-layout object
widget -- a gtk:widget center widget
Details:
The gtk:center-layout-end-widget function returns the end widget of the layout. The (setf gtk:center-layout-end-widget) function sets the end widget.
See also:
2024-4-19

GtkFixedLayout

Class gtk:fixed-layout-child
Superclasses:
gtk:layout-child, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
transform
The transform property of type gsk:transform (Read / Write)
The transform of the child widget.
Details:
The gtk:layout-child subclass for children in a gtk:fixed-layout class.
See also:
2024-4-23
Accessor gtk:fixed-layout-child-transform (object)
Syntax:
(gtk:fixed-layout-child-transform object) => transform
(setf (gtk:fixed-layout-child-transform object) transform)
Arguments:
object -- a gtk:fixed-layout-child widget
transform -- a gsk:transform instance
Details:
Accessor of the transform slot of the gtk:fixed-layout-child class. The gtk:fixed-layout-child-transform function retrieves the transformation of the child widget of a gtk:fixed-layout object. The (setf gtk:fixed-layout-child-transform) function sets the transform.
See also:
#2024-4-23
Class gtk:fixed-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:fixed-layout object is a layout manager which can place child widgets at fixed positions, and with fixed sizes.

Most applications should never use this layout manager. Fixed positioning and sizing requires constant recalculations on where children need to be positioned and sized. Other layout managers perform this kind of work internally so that application developers do not need to do it. Specifically, widgets positioned in a fixed layout manager will need to take into account:
  • Themes, which may change widget sizes.
  • Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts.
  • Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases.
In addition, the gtk:fixed-layout object does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is, normally GTK will order containers appropriately depending on the text direction, for example, to put labels to the right of the thing they label when using an RTL language. The gtk:fixed-layout object will not be able to do that for you.

Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application.
See also:
2024-4-23
Function gtk:fixed-layout-new ()
Returns:
The newly created gtk:fixed-layout object.
Details:
Creates a new gtk:fixed-layout object.
See also:
2024-4-24

GtkGridLayout

Class gtk:grid-layout-child
Superclasses:
gtk:layout-child, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
column
The column property of type :int (Read / Write)
The column to place the child widget in.
Default value: 0
column-span
The column-span property of type :int (Read / Write)
The number of columns the child spans to.
Allowed values: >= 1
Default value: 1
row
The row property of type :int (Read / Write)
The row to place the child widget in.
Default value: 0
row-span
The row-span property of type :int (Read / Write)
The number of rows the child widget spans to.
Allowed values: >= 1
Default value: 1
Slot Access Functions:
Details:
The gtk:layout-child subclass for children in a gtk:grid-layout object.
See also:
2024-4-23
Accessor gtk:grid-layout-child-column (object)
Syntax:
(gtk:grid-layout-child-column object) => column
(setf (gtk:grid-layout-child-column object) column)
Arguments:
object -- a gtk:grid-layout-child object
column -- an integer with the column to place the child widget in
Details:
Accessor of the column slot of the gtk:grid-layout-child class. The gtk:grid-layout-child-column function retrieves the column number to which child attaches its left side. The (setf gtk:grid-layout-child-column) function sets the column number.
See also:
#2024-4-23
Accessor gtk:grid-layout-child-column-span (object)
Syntax:
(gtk:grid-layout-child-column-span object) => span
(setf (gtk:grid-layout-child-column-span object) span)
Arguments:
object -- a gtk:grid-layout-child object
span -- an integer with the number of columns
Details:
Accessor of the column-span slot of the gtk:grid-layout-child class. The gtk:grid-layout-child-column-span function retrieves the number of columns that the child widget spans to. The (setf gtk:grid-layout-child-column-span) function sets the number of columns.
See also:
#2024-4-23
Accessor gtk:grid-layout-child-row (object)
Syntax:
(gtk:grid-layout-child-row object) => row
(setf (gtk:grid-layout-child-column object) row)
Arguments:
object -- a gtk:grid-layout-child object
row -- an integer with the row to place the child widget in
Details:
Accessor of the row slot of the gtk:grid-layout-child class. The gtk:grid-layout-child-row function retrieves the row number to which child attaches its top side. The (setf gtk:grid-layout-child-row) function sets the row number.
See also:
#2024-4-23
Accessor gtk:grid-layout-child-row-span (object)
Syntax:
(gtk:grid-layout-child-row-span object) => span
(setf (gtk:grid-layout-child-row-span object) span)
Arguments:
object -- a gtk:grid-layout-child object
span -- an integer with the number of rows
Details:
Accessor of the row-span slot of the gtk:grid-layout-child class. The gtk:grid-layout-child-row-span function retrieves the number of rows that the child widget spans to. The (setf gtk:grid-layout-child-row-span) function sets the number of rows.
See also:
#2024-4-23
Class gtk:grid-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
baseline-row
The baseline-row property of type :int (Read / Write)
The row to align to the baseline, when the valign property is set to the :baseline of the gtk:align enumeration.
Allowed values: >= 0
Default value: 0
column-homogeneous
The column-homogeneous property of type :boolean (Read / Write)
Whether all the columns in the grid have the same width.
Default value: false
column-spacing
The column-spacing property of type :int (Read / Write)
The amount of space between to consecutive columns.
Allowed values: [0,32767]
Default value: 0
row-homogeneous
The row-homogeneous property of type :boolean (Read / Write)
Whether all the rows in the grid have the same height.
Default value: false
row-spacing
The row-spacing property of type :int (Read / Write)
The amount of space between to consecutive rows.
Allowed values: [0,32767]
Default value: 0
Returned by:
Slot Access Functions:
Details:
Layout manager for grid like widgets. The gtk:grid-layout object is a layout manager which arranges child widgets in rows and columns, with arbitrary positions and horizontal/vertical spans.

Children have an "attach point" defined by the horizontal and vertical index of the cell they occupy. Children can span multiple rows or columns. The layout properties for setting the attach points and spans are set using the gtk:grid-layout-child object associated to each child widget.

The behaviour of the gtk:grid widget when several children occupy the same grid cell is undefined.

The gtk:grid-layout object can be used like a gtk:box-layout object if all children are attached to the same row or column. However, if you only ever need a single row or column, you should consider using the gtk:box-layout object.
See also:
2024-4-23
Accessor gtk:grid-layout-baseline-row (object)
Syntax:
(gtk:grid-layout-baseline-row object) => row
(setf (gtk:grid-layout-baseline-row object) row)
Arguments:
object -- a gtk:grid-layout object
row -- an integer with the row index
Details:
Accessor of the baseline-row slot of the gtk:grid-layout class. The gtk:grid-layout-baseline-row function retrieves the baseline row. The (setf gtk:grid-layout-baseline-row) function sets which row defines the global baseline for the entire grid.

Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the grid widget.
See also:
2024-4-23
Accessor gtk:grid-layout-column-homogeneous (object)
Syntax:
(gtk:grid-layout-column-homogeneous object) => homogeneous
(setf (gtk:grid-layout-column-homogeneous object) homogeneous)
Arguments:
object -- a gtk:grid-layout object
homogeneous -- a boolean whether all the columns in the grid have the same width
Details:
Accessor of the column-homogeneous slot of the gtk:grid-layout class. The gtk:grid-layout-column-homogeneous function checks whether all columns of the grid should have the same width. The (setf gtk:grid-layout-column-homogeneous) function sets whether all columns of the grid should have the same width.
See also:
2024-4-23
Accessor gtk:grid-layout-column-spacing (object)
Syntax:
(gtk:grid-layout-column-spacing object) => spacing
(setf (gtk:grid-layout-column-spacing object) spacing)
Arguments:
object -- a gtk:grid-layout object
spacing -- an integer with the amount of space between to consecutive columns
Details:
Accessor of the column-spacing slot of the gtk:grid-layout class. The gtk:grid-layout-column-spacing function retrieves the amount of space to insert between consecutive columns. The (setf gtk:grid-layout-column-spacing) function sets the spacing.
See also:
2024-4-23
Accessor gtk:grid-layout-row-homogeneous (object)
Syntax:
(gtk:grid-layout-row-homogeneous object) => homogeneous
(setf (gtk:grid-layout-row-homogeneous object) homogeneous)
Arguments:
object -- a gtk:grid-layout object
homogeneous -- a boolean whether all the rows in the grid have the same height
Details:
Accessor of the row-homogeneous slot of the gtk:grid-layout class. The gtk:grid-layout-row-homogeneous function checks whether all rows of the grid should have the same height. The (setf gtk:grid-layout-row-homogeneous) function sets whether all rows of the grid should have the same height.
See also:
2024-4-23
Accessor gtk:grid-layout-row-spacing (object)
Syntax:
(gtk:grid-layout-row-spacing object) => spacing
(setf (gtk:grid-layout-row-spacing object) spacing)
Arguments:
object -- a gtk:grid-layout object
spacing -- an integer with the amount of space between to consecutive rows
Details:
Accessor of the row-spacing slot of the gtk:grid-layout class. The gtk:grid-layout-row-spacing function retrieves the amount of space to insert between consecutive rows. The (setf gtk:grid-layout-row-spacing) function sets the spacing.
See also:
2024-4-23
Function gtk:grid-layout-new ()
Returns:
The newly created gtk:grid-layout object.
Details:
Creates a new grid layout.
See also:
2024-4-23
Function gtk:grid-layout-row-baseline-position (layout row)
Syntax:
(gtk:grid-layout-row-baseline-position layout) => position
(setf (gtk:grid-layout-row-baseline-position layout) position)
Arguments:
layout -- a gtk:grid-layout object
row -- an integer with the row index
position -- a gtk:baseline-position value
Details:
The gtk:grid-layout-row-baseline-position function returns the baseline position of row. The (setf gtk:grid-layout-row-baseline-position) function sets how the baseline should be positioned on row of the grid, in case that row is assigned more space than is requested. The default value is the :center value of the gtk:baseline-position enumeration.
See also:
2024-4-23

GtkOverlayLayout

Class gtk:overlay-layout-child
Superclasses:
gtk:layout-child, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
clip-overlay
The clip-overlay property of type :boolean (Read / Write)
Whether the child widget should be clipped to fit the size of the parent.
Default value: false
measure
The measure property of type :boolean (Read / Write)
Whether the child widget size should contribute to the overlay layout measurement.
Default value: false
Slot Access Functions:
Details:
The gtk:overlay-layout-child subclass for children in a gtk:overlay-layout object.
See also:
2024-4-23
Accessor gtk:overlay-layout-child-clip-overlay (object)
Syntax:
(gtk:overlay-layout-child-clip-overlay object) => clip
(setf (gtk:overlay-layout-child-clip-overlay object) clip)
Arguments:
object -- a gtk:overlay-layout-child object
clip -- a boolean whether the child widget is clipped
Details:
Accessor of the clip-overlay slot of the gtk:overlay-layout-child class. The gtk:overlay-layout-child-clip-overlay function retrieves whether the child widget is clipped. The (setf gtk:overlay-layout-child-clip-overlay) function sets whether to clip the child widget.
See also:
#2024-4-23
Accessor gtk:overlay-layout-child-measure (object)
Syntax:
(gtk:overlay-layout-child-measure object) => measure
(setf (gtk:overlay-layout-child-measure object) measure)
Arguments:
object -- a gtk:overlay-layout-child object
measure -- a boolean whether to measure the child widget
Details:
Accessor of the measure slot of the gtk:overlay-layout-child class. The gtk:overlay-layout-child-measure function retrieves whether the child widget is measured. The (setf gtk:overlay-layout-child-measure) function sets whether to measure the child widget.
See also:
#2024-4-23
Class gtk:overlay-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:overlay-layout object is the layout manager used by the gtk:overlay widget. It places widgets as overlays on top of the main child.

This is not a reusable layout manager, since it expects its widget to be a gtk:overlay widget. It only listed here so that its layout properties get documented.
See also:
2024-4-23
Function gtk:overlay-layout-new ()
Returns:
The newly created gtk:overlay-layout object
Details:
Creates a new overlay layout manager.
See also:
2024-4-23

GtkCustomLayout

Class gtk:custom-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:custom-layout class is a convenience type meant to be used as a transition mechanism between gtk:widget objects implementing a layout policy, and gtk:layout-manager classes.

A gtk:custom-layout object uses closures matching to the old gtk:widget virtual functions for size negotiation, as a convenience API to ease the porting towards the corresponding gtk:layout-manager virtual functions.
2024-4-23

GtkConstraint

Interface gtk:constraint-target
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
gtk:about-dialog, gtk:action-bar, gtk:app-chooser-button, gtk:app-chooser-dialog, gtk:app-chooser-widget, gtk:application-window, gtk:aspect-frame, gtk:assistant, gtk:box, gtk:button, gtk:calendar, gtk:cell-view, gtk:center-box, gtk:check-button, gtk:color-button, gtk:color-chooser-dialog, gtk:color-chooser-widget, gtk:color-dialog-button, gtk:column-view, gtk:combo-box, gtk:combo-box-text, gtk:dialog, gtk:drag-icon, gtk:drawing-area, gtk:drop-down, gtk:editable-label, gtk:emoji-chooser, gtk:entry, gtk:expander, gtk:file-chooser-dialog, gtk:file-chooser-widget, gtk:fixed, gtk:flow-box, gtk:flow-box-child, gtk:font-button, gtk:font-chooser-dialog, gtk:font-chooser-widget, gtk:font-dialog-button, gtk:frame, gtk:gl-area, gtk:graphics-offload, gtk:grid, gtk:grid-view, gtk:header-bar, gtk:icon-view, gtk:image, gtk:info-bar, gtk:inscription, gtk:label, gtk:level-bar, gtk:link-button, gtk:list-base, gtk:list-box, gtk:list-box-row, gtk:lock-button, gtk:media-controls, gtk:menu-button, gtk:message-dialog, gtk:notebook, gtk:overlay, gtk:page-setup-unix-dialog, gtk:paned, gtk:password-entry, gtk:picture, gtk:popover, gtk:popover-menu, gtk:popover-menu-bar, gtk:print-unix-dialog, gtk:progress-bar, gtk:range, gtk:revealer, gtk:scale, gtk:scale-button, gtk:scrollbar, gtk:scrolled-window, gtk:search-bar, gtk:search-entry, gtk:separator, gtk:shortcut-label, gtk:shortcuts-group, gtk:shortcuts-section, gtk:shortcuts-shortcut, gtk:shortcuts-window, gtk:spin-button, gtk:spinner, gtk:stack, gtk:stack-sidebar, gtk:stack-switcher, gtk:statusbar, gtk:switch, gtk:text, gtk:text-view, gtk:toggle-button, gtk:tree-expander, gtk:tree-view, gtk:video, gtk:viewport, gtk:volume-button, gtk:widget, gtk:window, gtk:window-controls, gtk:window-handle
Direct Slots:
None
Details:
The gtk:constraint-target interface is implemented by objects that can be used as source or target in gtk:constraint objects. Besides gtk:widget objects, it is also implemented by the gtk:constraint-guide object.
See also:
2025-3-25
Class gtk:constraint
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
constant
The constant property of type :double (Read / Write / Construct only)
The constant value to be added to the source-attribute property.
Default value: 0
multiplier
The multiplier property of type :double (Read / Write / Construct only)
The multiplication factor to be applied to the source-attribute property.
Default value: 1
relation
The relation property of type gtk:constraint-relation (Read / Write / Construct only)
The order relation between the terms of the constraint.
Default value: :eq
source
The source property of type gtk:constraint-target (Read / Write / Construct only)
The source of the constraint. The constraint will set the target-attribute property of the target using the source-attribute property of the source widget.
source-attribute
The source-attribute property of type gtk:constraint-attribute (Read / Write / Construct only)
The attribute of the source property read by the constraint.
Default value: :none
strength
The strength property of type :int (Read / Write / Construct only)
The strength of the constraint. The strength can be expressed either using one of the symbolic values of the gtk:constraint-strength enumeration, or any positive integer.
Allowed values: [0, 1001001000]
Default value: 1001001000
target
The target property of type gtk:constraint-target (Read / Write / Construct only)
The target of the constraint. The constraint will set the target-attribute property of the target using the source-attribute property of the source widget.
target-attribute
The target-attribute property of type gtk:constraint-attribute (Read / Write / Construct only)
The attribute of the target property set by the constraint.
Default value: :none
Returned by:
Slot Access Functions:
Details:
The gtk:constraint class describes a constraint between an attribute on a widget and another attribute on another widget, expressed as a linear equation.

The typical equation for a constraint is:
target.target_attr = source.source_attr × multiplier + constant  
Each gtk:constraint object is part of a system that will be solved by a gtk:constraint-layout object in order to allocate and position each child widget.

The source and target widgets, as well as their attributes, of a gtk:constraint object are immutable after creation.
See also:
2025-3-25
Accessor gtk:constraint-constant (object)
Syntax:
(gtk:constraint-constant object) => constant
Arguments:
object -- a gtk:constraint object
constant -- a double float for the constant value to be added to the source-attribute property
Details:
Accessor of the constant slot of the gtk:constraint class. The gtk:constraint-constant function retrieves the constant factor added to the source attributes' value.
See also:
2025-3-25
Accessor gtk:constraint-multiplier (object)
Syntax:
(gtk:constraint-multiplier object) => multiplier
Arguments:
object -- a gtk:constraint object
multiplier -- a double float for the multiplication factor to be applied to the source-attribute property
Details:
Accessor of the multiplier slot of the gtk:constraint class. The gtk:constraint-multiplier function retrieves the multiplication factor applied to the source attribute's value.
See also:
2025-3-25
Accessor gtk:constraint-relation (object)
Syntax:
(gtk:constraint-relation object) => relation
Arguments:
object -- a gtk:constraint object
relation -- a gtk:constraint-relation value for the order relation between the terms of the constraint
Details:
Accessor of the relation slot of the gtk:constraint class. The gtk:constraint-relation function the order relation between the terms of the constraint.
See also:
2025-3-25
Accessor gtk:constraint-source (object)
Syntax:
(gtk:constraint-source object) => source
Arguments:
object -- a gtk:constraint object
source -- a gtk:constraint-target object
Details:
Accessor of the source slot of the gtk:constraint class. The gtk:constraint-source function retrieves the gtk:constraint-target value used as the source for the constraint.

If the source property is set to nil, the constraint will use the gtk:constraint-layout object of the widget.
See also:
2025-3-25
Accessor gtk:constraint-source-attribute (object)
Syntax:
(gtk:constraint-source-attribute object) => attribute
Arguments:
object -- a gtk:constraint object
attribute -- a gtk:constraint-attribute value for the attribute of the source property read by the constraint
Details:
Accessor of the source-attribute slot of the gtk:constraint class. The gtk:constraint-source-attribute function retrieves the attribute of the source to be read by the constraint.
See also:
2025-3-25
Accessor gtk:constraint-strength (object)
Syntax:
(gtk:constraint-strength object) => strength
Arguments:
object -- a gtk:constraint object
strength -- an integer for the strength of the constraint
Details:
Accessor of the source-attribute slot of the gtk:constraint class. The gtk:constraint-strength function returns the strength of the constraint. The strength can be expressed either using one of the values of the gtk:constraint-strength enumeration, or any positive integer value.
See also:
2025-3-25
Accessor gtk:constraint-target (object)
Syntax:
(gtk:constraint-target object) => target
Arguments:
object -- a gtk:constraint object
source -- a gtk:constraint-target object
Details:
Accessor of the target slot of the gtk:constraint class. The gtk:constraint-target function retrieves the gtk:constraint-target value used as the target for the constraint. If the target property is set to nil, the constraint will use the gtk:constraint-layout object of the widget.
See also:
2025-3-25
Accessor gtk:constraint-target-attribute (object)
Syntax:
(gtk:constraint-target-attribute object) => attribute
Arguments:
object -- a gtk:constraint object
attribute -- a gtk:constraint-attribute value for the attribute of the target property set by the constraint
Details:
Accessor of the target-attribute slot of the gtk:constraint class. The gtk:constraint-target function retrieves the attribute of the target to be set by the constraint.
See also:
2025-3-25
Function gtk:constraint-new (target target-attribute relation source source-attribute multiplier constant strength)
Arguments:
target -- a gtk:constraint-target object
target-attribute -- a gtk:constraint-attribute value for the attribute of target to be set
relation -- a gtk:constraint-relation value for the relation equivalence between target-attribute and source-attribute
source -- a gtk:constraint-target object
source-attribute -- a gtk:constraint-attribute value for the attribute of source to be set
multiplier -- a number coerced to a double float for a multiplication factor to be applied to source-attribute
constant -- a number coerced to a double float for a constant factor to be added to source-attribute
strength -- a gtk:constraint-strength value for the strength of the constraint
Returns:
The newly created gtk:constraint object.
Details:
Creates a new gtk:constraint object representing a relation between a layout attribute on a source and a layout attribute on a target.
See also:
2025-3-25
Function gtk:constraint-new-constant (target target-attribute relation constant strength)
Arguments:
target -- a gtk:constraint-target object
target-attribute -- a gtk:constraint-attribute value for the attribute of target to be set
relation -- a gtk:constraint-relation value for the relation equivalence between target-attribute and source-attribute
constant -- a number coerced to a double float for a constant factor to be added to source-attribute
strength -- a gtk:constraint-strength value for the strength of the constraint
Returns:
The newly created gtk:constraint object.
Details:
Creates a new gtk:constraint object representing a relation between a layout attribute on a target and a constant value.
See also:
2025-3-25
Function gtk:constraint-is-required (constraint)
Arguments:
constraint -- a gtk:constraint object
Returns:
True if the constraint is required.
Details:
Checks whether the constraint is a required relation for solving the constraint layout.
See also:
2025-3-25
Function gtk:constraint-is-attached (constraint)
Arguments:
constraint -- a gtk:constraint object
Returns:
True if the constraint is attached.
Details:
Checks whether the constraint is attached to a gtk:constraint-layout object, and it is contributing to the layout.
See also:
2025-3-25
Function gtk:constraint-is-constant (constraint)
Arguments:
constraint -- a gtk:constraint object
Returns:
True if the constraint is as constant relation.
Details:
Checks whether the constraint describes a relation between an attribute on the target and a constant value.
See also:
2025-3-25

GtkConstraintGuide

Class gtk:constraint-guide
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
max-height
The max-height property of type :int (Read / Write)
The maximum height of the guide.
Allowed values: >= 0
Default value: 2147483647
max-width
The max-width property of type :int (Read / Write)
The maximum width of the guide.
Allowed values: >= 0
Default value: 2147483647
min-height
The min-height property of type :int (Read / Write)
The minimum height of the guide.
Allowed values: >= 0
Default value: 0
min-width
The min-width property of type :int (Read / Write)
The minimum width of the guide.
Allowed values: >= 0
Default value: 0
name
The name property of type :string (Read / Write)
The name that identifies the gtk:constraint-guide object, for debugging.
Default value: nil
nat-height
The nat-height property of type :int (Read / Write)
The preferred, or natural, height of the guide.
Allowed values: >= 0
Default value: 0
nat-width
The nat-width property of type :int (Read / Write)
The preferred, or natural, width of the guide.
Allowed values: >= 0
Default value: 0
strength
The name property of type :string (Read / Write)
The gtk:constraint-strength value to be used for the constraint on the natural size of the guide.
Default value: :medium
Returned by:
Slot Access Functions:
Details:
An object that can be added to a gtk:constraint-layout object and be used in constraints like a widget, without being drawn.

Guides have a minimum, maximum and natural size. Depending on the constraints that are applied, they can act like a guideline that widgets can be aligned to, or like 'flexible space'.
See also:
2024-4-23
Accessor gtk:constraint-guide-max-height (object)
Syntax:
(gtk:constraint-guide-max-height object) => height
(setf (gtk:constraint-guide-max-height object) height)
Arguments:
object -- a gtk:constraint-guide object
height -- an integer with the maximum height of the guide
Details:
Accessor of the max-height slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-max-width (object)
Syntax:
(gtk:constraint-guide-max-width object) => width
(setf (gtk:constraint-guide-max-width object) width)
Arguments:
object -- a gtk:constraint-guide object
width -- an integer with the maximum width of the guide
Details:
Accessor of the max-width slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-min-height (object)
Syntax:
(gtk:constraint-guide-min-height object) => height
(setf (gtk:constraint-guide-min-height object) height)
Arguments:
object -- a gtk:constraint-guide object
height -- an integer with the minimum height of the guide
Details:
Accessor of the min-height slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-min-width (object)
Syntax:
(gtk:constraint-guide-min-width object) => width
(setf (gtk:constraint-guide-min-width object) width)
Arguments:
object -- a gtk:constraint-guide object
width -- an integer with the minimum width of the guide
Details:
Accessor of the min-width slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-name (object)
Syntax:
(gtk:constraint-guide-name object) => name
(setf (gtk:constraint-guide-name object) name)
Arguments:
object -- a gtk:constraint-guide object
name -- a string with the name for the guide
Details:
Accessor of the name slot of the gtk:constraint-guide class. The gtk:constraint-guide-name function retrieves the name for the constraint guide. The (setf gtk:constraint-guide-name) function sets a name. The name is useful for debugging purposes.
See also:
2024-4-23
Accessor gtk:constraint-guide-nat-height (object)
Syntax:
(gtk:constraint-guide-nat-height object) => height
(setf (gtk:constraint-guide-nat-height object) height)
Arguments:
object -- a gtk:constraint-guide object
height -- an integer with the preferred, or natural, height of the guide
Details:
Accessor of the nat-height slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-nat-width (object)
Syntax:
(gtk:constraint-guide-nat-width object) => width
(setf (gtk:constraint-guide-nat-width object) width)
Arguments:
object -- a gtk:constraint-guide object
width -- an integer with the preferred, or natural, width of the guide
Details:
Accessor of the nat-width slot of the gtk:constraint-guide class.
See also:
2024-4-23
Accessor gtk:constraint-guide-strength (object)
Syntax:
(gtk:constraint-guide-strength object) => strength
(setf (gtk:constraint-guide-strength object) strength)
Arguments:
object -- a gtk:constraint-guide object
strength -- a gtk:constraint-strength value with the strength of the constraint on the natural size
Details:
Accessor of the strength slot of the gtk:constraint-guide class. The gtk:constraint-guide-strength function retrieves the strength of the constraint on the natural size of the given guide. The (setf gtk:constraint-guide-strength) function sets the strength of the constraint.
See also:
2024-4-23
Function gtk:constraint-guide-new ()
Returns:
The newly created gtk:constraint-guide object.
Details:
Creates a new constraint guide.
See also:
2024-4-23

GtkConstraintLayout

Class gtk:constraint-layout-child
Superclasses:
gtk:layout-child, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:constraint-layout-child subclass for children in a gtk:constraint-layout object.
See also:
2024-4-23
Class gtk:constraint-layout
Superclasses:
gtk:layout-manager, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:constraint-layout object is a layout manager that uses relations between widget attributes, expressed via gtk:constraint instances, to measure and allocate widgets.
How do constraints work:
Constraints are objects defining the relationship between attributes of a widget. You can read the description of the gtk:constraint class to have a more in depth definition.

By taking multiple constraints and applying them to the children of a widget using the gtk:constraint-layout object, it is possible to describe complex layout policies. Each constraint applied to a child or to the parent widgets contributes to the full description of the layout, in terms of parameters for resolving the value of each attribute.

It is important to note that a layout is defined by the totality of constraints. Removing a child, or a constraint, from an existing layout without changing the remaining constraints may result in an unstable or unsolvable layout.

Constraints have an implicit "reading order". You should start describing each edge of each child, as well as their relationship with the parent container, from the top left (or top right, in RTL languages), horizontally first, and then vertically.

A constraint-based layout with too few constraints can become "unstable", that is: have more than one solution. The behavior of an unstable layout is undefined.

A constraint-based layout with conflicting constraints may be unsolvable, and lead to an unstable layout. You can use the strength property to "nudge" the layout towards a solution.
GtkConstraintLayout as GtkBuildable:
The gtk:constraint-layout class implements the gtk:buildable interface and has a custom constraints element which allows describing constraints in a gtk:builder object.

An example of a UI definition fragment specifying a constraint:
<object class="GtkConstraintLayout">
  <constraints>
    <constraint target="button" target-attribute="start"
                relation="eq"
                source="super" source-attribute="start"
                constant="12"
                strength="required" />
    <constraint target="button" target-attribute="width"
                relation="ge"
                constant="250"
                strength="strong" />
  </constraints>
</object>    
The definition above will add two constraints to the gtk:constraint-layout object:
  • a required constraint between the leading edge of "button" and the leading edge of the widget using the constraint layout, plus 12 pixels,
  • a strong, constant constraint making the width of "button" greater than, or equal to 250 pixels.
The "target" and "target-attribute" attributes are required.

The "source" and "source-attribute" attributes of the "constraint" element are optional. If they are not specified, the constraint is assumed to be a constant.

The "relation" attribute is optional. If not specified, the constraint is assumed to be an equality.

The "strength" attribute is optional. If not specified, the constraint is assumed to be required.

The "source" and "target" attributes can be set to "super" to indicate that the constraint target is the widget using the gtk:constraint-layout object.

There can be "constant" and "multiplier" attributes.

Additionally, the "constraints" element can also contain a description of the gtk:constraint-guide object used by the layout:
<constraints>
  <guide min-width="100" max-width="500" name="hspace"/>
  <guide min-height="64" nat-height="128" name="vspace" strength="strong"/>
</constraints>    
The "guide" element has the following optional attributes:
  • "min-width", "nat-width", and "max-width", describe the minimum, natural, and maximum width of the guide, respectively
  • "min-height", "nat-height", and "max-height", describe the minimum, natural, and maximum height of the guide, respectively
  • "strength" describes the strength of the constraint on the natural size of the guide, if not specified, the constraint is assumed to have a medium strength
  • "name" describes a name for the guide, useful when debugging
Using the Visual Format Language:
Complex constraints can be described using a compact syntax called VFL, or Visual Format Language.

The Visual Format Language describes all the constraints on a row or column, typically starting from the leading edge towards the trailing one. Each element of the layout is composed by "views", which identify a gtk:constraint-target object.

For instance:
[button]-[textField]    
Describes a constraint that binds the trailing edge of "button" to the leading edge of "textField", leaving a default space between the two.

Using VFL is also possible to specify predicates that describe constraints on attributes like width and height:
// Width must be greater than, or equal to 50
[button(>=50)]

// Width of button1 must be equal to width of button2 [button1(==button2)]
The default orientation for a VFL description is horizontal, unless otherwise specified:
// horizontal orientation, default attribute: width
H:[button(>=150)]

// vertical orientation, default attribute: height V:[button1(==button2)]
It is also possible to specify multiple predicates, as well as their strength:
// minimum width of button must be 150
// natural width of button can be 250
[button(>=150@required, ==250@medium)]    
Finally, it is also possible to use simple arithmetic operators:
// width of button1 must be equal to width of button2
// divided by 2 plus 12
[button1(button2 / 2 + 12)]    
See also:
2024-4-23
Function gtk:constraint-layout-new ()
Returns:
The newly created gtk:constraint-layout object.
Details:
Creates a new gtk:constraint-layout layout manager.
See also:
2023-4-23
Function gtk:constraint-layout-add-constraint (layout constraint)
Arguments:
layout -- a gtk:constraint-layout object
constraint -- a gtk:constraint object
Details:
Adds a gtk:constraint object to the layout manager. The source and target properties of constraint can be:
  • set to nil to indicate that the constraint refers to the widget using layout
  • set to the gtk:widget object using layout
  • set to a child of the gtk:widget object using layout
  • set to a gtk:constraint-guide object that is part of layout
The layout acquires the ownership of constraint after calling this function.
See also:
2024-4-29
Function gtk:constraint-layout-remove-constraint (layout constraint)
Arguments:
layout -- a gtk:constraint-layout object
constraint -- a gtk:constraint object
Details:
Removes constraint from the layout manager, so that it no longer influences the layout.
See also:
2024-4-29
Function gtk:constraint-layout-remove-all-constraints (layout)
Arguments:
layout -- a gtk:constraint-layout object
Details:
Removes all constraints from the layout manager.
See also:
#2024-4-23
Function gtk:constraint-layout-add-guide (layout guide)
Arguments:
layout -- a gtk:constraint-layout object
guide -- a gtk:constraint-guide object
Details:
Adds a guide to layout. A guide can be used as the source or target of constraints, like a widget, but it is not visible.

The layout acquires the ownership of guide after calling this function.
See also:
2024-4-29
Function gtk:constraint-layout-remove-guide (layout guide)
Arguments:
layout -- a gtk:constraint-layout object
guide -- a gtk:constraint-guide object
Details:
Removes guide from the layout manager, so that it no longer influences the layout.
See also:
#2024-4-23

Display Widgets

GtkLabel

Class gtk:label
Superclasses:
Documented Subclasses:
None
Direct Slots:
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of style attributes to apply to the text of the label.
ellipsize
The ellipsize property of type pango:ellipsize-mode (Read / Write)
The preferred place to ellipsize the string, if the label does not have enough room to display the entire string, specified as a value of the pango:ellipsize-mode enumeration. Note that setting this property to a value other than :none has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless the tab-expand child property of the tab is set to true. Other ways to set a width of the label are the gtk:widget-size-request and gtk:label-width-chars functions.
Default value: :none
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model whose contents will be appended to the context menu.
justify
The justify property of type gtk:justification (Read / Write)
The alignment of the lines in the text of the label relative to each other. This does not affect the alignment of the label within its allocation. See the xalign property for that.
Default value: :left
label
The label property of type :string (Read / Write)
The text of the label.
Default value: ""
lines
The lines property of type :int (Read / Write)
The number of lines to which an ellipsized, wrapping label should be limited. This property has no effect if the label is not wrapping or ellipsized. Set this property to -1 if you do not want to limit the number of lines.
Allowed values: >= -1
Default value: -1
max-width-chars
The max-width-chars property of type :int (Read / Write)
The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on text layout for details of how the width-chars and max-width-chars properties determine the width of ellipsized and wrapped labels.
Allowed values: >= -1
Default value: -1
mnemonic-keyval
The mnemonic-keyval property of :uint (Read)
The mnemonic accelerator key for this label.
Default value: #xffffff
mnemonic-widget
The mnemonic-widget property of type gtk:widget (Read / Write)
The widget to be activated when the mnemonic key of the label is pressed.
natural-wrap-mode
The natural-wrap-mode property of type gtk:natural-wrap-mode (Read / Write)
Select the line wrapping for the natural size request. This only affects the natural size requested. For the actual wrapping used, see the wrap-mode property. The default is the :inherit value, which inherits the behavior of the wrap-mode property. Since 4.6
Default value: :inherit
selectable
The selectable property of type :boolean (Read / Write)
Whether the label text can be selected with the mouse.
Default value: false
single-line-mode
The single-line-mode property of type :boolean (Read / Write)
Whether the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to the (ascent + descent) value of the font. This can be an advantage in situations where resizing the label because of text changes would be distracting, for example in a statusbar.
Default value: false
tabs
The tabs property of type pango:tab-array (Read / Write)
Custom tabs for this label.
use-markup
The use-markup property of type :boolean (Read / Write)
The text of the label includes XML Pango markup.
Default value: false
use-underline
The use-underline property of type :boolean (Read / Write)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: false
width-chars
The width-chars property of :int (Read / Write)
The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on text layout for details of how the width-chars and max-width-chars properties determine the width of ellipsized and wrapped labels.
Allowed values: >= -1
Default value: -1
wrap
The wrap property of type :boolean (Read / Write)
If set, wrap lines if the text becomes too wide.
Default value: false
wrap-mode
The wrap-mode property of type pango:wrap-mode (Read / Write)
If line wrapping is on, see the wrap property, this controls how the line wrapping is done. The default is :word, which means wrap on word boundaries.
Default value: :word
xalign
The xalign property of type :float (Read / Write)
Determines the horizontal aligment of the label text inside the size allocation of the label. Compare this to the halign property, which determines how the size allocation is positioned in the space available for the label.
Allowed values: [0.0, 1.0]
Default value: 0.5
yalign
The yalign property of type :float (Read / Write)
Determines the vertical aligment of the label text inside the size allocation of the label. Compare this to valign property, which determines how the size allocation is positioned in the space available for the label.
Allowed values: [0.0, 1.0]
Default value: 0.5
Returned by:
Slot Access Functions:
Details:
The gtk:label widget displays a small amount of text. As the name implies, most labels are used to label another widget such as a gtk:button widget.

Figure: GtkLabel

Mnemonics
Labels may contain mnemonics. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as "_File", to the gtk:label-new-with-mnemonic or gtk:label-set-text-with-mnemonic functions.

Mnemonics automatically activate any activatable widget the label is inside, such as a gtk:button widget. If the label is not inside the target widget of the mnemonic, you have to tell the label about the target using the gtk:label-mnemonic-widget function. Here is a simple example where the label is inside a button:
;; Pressing Alt+H will activate this button
(let* ((label (gtk:label-new-with-mnemonic "_Hello"))
       (button (make-instance 'gtk:button
                              :child label)))
   ... )  
There is a convenience function to create buttons with a mnemonic label already inside:
;; Pressing Alt+H will activate this button
(gtk:button-new-with-mnemonic "_Hello")  
To create a mnemonic for a widget alongside the label, such as a gtk:entry widget, you have to point the label at the text entry with the gtk:label-mnemonic-widget function:
;; Pressing Alt+H will focus the text entry
(let ((entry (make-instance 'gtk:entry))
      (label (gtk:label-new-with-mnemonic "_Hello")))
   (setf (gtk:label-mnemonic-widget label) entry)
   ... )  
Markup (styled text)
To make it easy to format text in a label, changing colors, fonts, and so on, label text can be provided in a simple markup format. Here is how to create a label with a small font:
(let ((label (make-instance 'gtk:label)))
  (gtk:label-set-markup label
                        "<small>Small text</small>")
  ... )  
See complete documentation of available tags in the Pango manual.

The markup passed to the gtk:label-set-markup function must be valid. For example, literal <, > and & characters must be escaped as <, gt;, and &. If you pass text obtained from the user, file, or a network to the gtk:label-set-markup function, you will want to escape it with the g_markup_escape_text() or g_markup_printf_escaped() functions.

Markup strings are just a convenient way to set the pango:attr-list instance on a label. The gtk:label-attributes function may be a simpler way to set attributes in some cases. Be careful though, a pango:attr-list instance tends to cause internationalization problems, unless you are applying attributes to the entire string, that is, unless you set the range of each attribute to [0, G_MAXINT]). The reason is that specifying the start_index and end_index for a pango:attribute structure requires knowledge of the exact string being displayed, so translations will cause problems.

Selectable labels
Labels can be made selectable with the gtk:label-selectable function. Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information - such as error messages - should be made selectable.

Text layout
A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango.

Labels can automatically wrap text if you call the gtk:label-wrap function.

The gtk:label-justify function sets how the lines in a label align with one another. If you want to set how the label as a whole aligns in its available space, see the halign and valign properties.

The width-chars and max-width-chars properties can be used to control the size allocation of ellipsized or wrapped labels. For ellipsizing labels, if either is specified and less than the actual text size, it is used as the minimum width, and the actual text size is used as the natural width of the label. For wrapping labels, the width-chars property is used as the minimum width, if specified, and the max-width-chars property is used as the natural width. Even if the max-width-chars property specified, wrapping labels will be rewrapped to use all of the available width.

Note that the interpretation of the width-chars and max-width-chars properties has changed a bit with the introduction of "width-for-height" geometry management.

Links
GTK supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the a with href and title attributes. GTK renders links similar to the way they appear in web browsers, with colored, underlined text. The title attribute is displayed as a tooltip on the link. An example looks like this:
(gtk:label-set-markup label
                      "Go to <a href="http://gtk.org/">GTK Website</a> ...")  
It is possible to implement custom handling for links and their tooltips with the "activate-link" signal and the gtk:label-current-uri function.
GtkLabel as GtkBuildable:
The gtk:label implementation of the gtk:buildable interface supports a custom <attributes> element, which supports any number of <attribute> elements. The <attribute> element has attributes named name, value, start and end and allows you to specify PangoAttribute values for the label.

Example: A UI definition fragment specifying Pango attributes
 <object class="GtkLabel">
  <attributes>
     <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
     <attribute name="background" value="red" start="5" end="10"/>"
   </attributes>
 </object>    
The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead.
CSS nodes:
label
├── [selection]
├── [link]
┊
╰── [link]    
The gtk:label implementation has a single CSS node with the name label. A wide variety of style classes may be applied to labels, such as the .title, .subtitle, .dim-label style classes. In the gtk:shortcuts-window widget, labels are used wth the .keycap style class.

If the label has a selection, it gets a subnode with name selection.

If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. In this case, the label node also gets a .link style class.
Accessibility:
The gtk:label implementation uses the :label role of the gtk:accessible-role enumeration.
Shortcuts and Gestures:
The gtk:label implementation supports the following keyboard shortcuts, when the cursor is visible.
  • Shift+F10 or Menu opens the context menu.
  • Ctrl+A or Ctrl+/ selects all.
  • Ctrl+Shift+A or Ctrl+ unselects all.
Additionally, the following signals have default keybindings.
  • GtkLabel::activate-current-link
  • GtkLabel::copy-clipboard
  • GtkLabel::move-cursor
Action Details:
The gtk:label implementation defines a set of built-in actions.
clipboard.copy
Copies the text to the clipboard.
clipboard.cut
Does not do anything, since text in labels cannot be deleted.
clipboard.paste
Does not do anything, since text in labels cannot be edited.
link.open
Opens the link, when activated on a link inside the label.
link.copy
Copies the link to the clipboard, when activated on a link inside the label.
menu.popup
Opens the context menu.
selection.delete
Does not do anything, since text in labels cannot be deleted.
selection.select-all
Selects all of the text, if the label allows selection.
Signal Details:
The "activate-current-link" signal
lambda (label)    :action      
label
The gtk:label widget on which the signal was emitted.
A keybinding signal which gets emitted when the user activates a link in the label. Applications may also emit the signal with the g:signal-emit function if they need to control activation of URIs programmatically. The default bindings for this signal are all forms of the Enter key.
The "activate-link" signal
lambda (label uri)    :run-last      
label
The gtk:label widget on which the signal was emitted.
uri
The string with the URI that is activated.
Returns
True if the link has been activated.
The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call the gtk:file-launcher-launch function.
The "copy-clipboard" signal
lambda (label)    :action      
label
The gtk:label widget which received the signal.
The signal is a keybinding signal which gets emitted to copy the selection to the clipboard. The default binding for this signal is the Ctrl-c key.
The "move-cursor" signal
lambda (label step count extend)    :action      
label
The gtk:label widget which received the signal.
step
The granularity of the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
extend
True if the move should extend the selection.
The signal is a keybinding signal which gets emitted when the user initiates a cursor movement. If the cursor is not visible in the label, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here.
  • Arrow keys move by individual characters/lines.
  • Ctrl-arrow key combinations move by words/paragraphs.
  • Home/End keys move to the ends of the buffer.
See also:
2024-11-29
Accessor gtk:label-attributes (object)
Syntax:
(gtk:label-attributes object) => attrs
(setf (gtk:label-attributes object) attrs)
Arguments:
object -- a gtk:label widget
attrs -- a pango:attr-list instance
Details:
Accessor of the attributes slot of the gtk:label class. The gtk:label-attributes function gets the attribute list that was set on the label, if any. The (setf gtk:label-attributes) function sets a attribute list. The attributes in the list are applied to the label text.

This function does not reflect attributes that come from the labels markup, see the gtk:label-set-markup function. If you want to get the effective attributes for the label, use
(pango:layout-attributes (gtk:label-layout label))  
Notes:
The attributes set with this function will be applied and merged with any other attributes previously effected by way of the use-underline or use-markup properties. While it is not recommended to mix markup strings with manually set attributes, if you must, know that the attributes will be applied to the label after the markup string is parsed.
See also:
2024-4-24
Accessor gtk:label-ellipsize (object)
Syntax:
(gtk:label-ellipsize object) => mode
(setf (gtk:label-ellipsize object) mode)
Arguments:
object -- a gtk:label widget
mode -- a value of the pango:ellipsize-mode enumeration
Details:
Accessor of the ellipsize slot of the gtk:label class. The gtk:label-ellipsize function returns the ellipsizing position of the label. The (setf gtk:label-ellipsize) function sets the mode used to ellipsize, add an ellipsis: "...", to the text if there is not enough space to render the entire string.
See also:
2024-4-24
Accessor gtk:label-extra-menu (object)
Syntax:
(gtk:label-extra-menu object) => menu
(setf (gtk:label-extra-menu object) menu)
Arguments:
object -- a gtk:label widget
menu -- a g:menu-model object
Details:
Accessor of the extra-menu slot of the gtk:label class. The gtk:label-extra-menu function gets the menu model. The (setf gtk:label-extra-menu) function sets a menu model to add when constructing the context menu for the label.
See also:
2024-4-24
Accessor gtk:label-justify (object)
Syntax:
(gtk:label-justify object) => justify
(setf (gtk:label-justify object) justify)
Arguments:
object -- a gtk:label widget
justify -- a value of the gtk:justification enumeration
Details:
Accessor of the justify slot of the gtk:label class. The gtk:label-justify function returns the justification of the label. The (setf gtk:label-justify) function sets the alignment of the lines in the text of the label relative to each other.

The :left value is the default value when the widget is first created with the gtk:label-new function. If you instead want to set the alignment of the label as a whole, use the gtk:widget-halign function instead. The (setf gtk:label-justify) function has no effect on labels containing only a single line.
See also:
2024-4-24
Accessor gtk:label-label (object)
Syntax:
(gtk:label-label object) => text
(setf (gtk:label-label object) text)
Arguments:
object -- a gtk:label widget
text -- a string with the text for the label
Details:
Accessor of the label slot of the gtk:label class. The gtk:label-label function returns the text of the label widget including any embedded underlines indicating mnemonics and Pango markup. The (setf gtk:label-label) function sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the use-underline and use-markup properties.

See also the gtk:label-text function, which fetches the text from a label, as displayed on the screen.
See also:
2024-4-24
Accessor gtk:label-lines (object)
Syntax:
(gtk:label-lines object) => lines
(setf (gtk:label-lines object) lines)
Arguments:
object -- a gtk:label widget
lines -- an integer with the desired number of lines, or -1
Details:
Accessor of the lines slot of the gtk:label class. The gtk:label-lines function gets the number of lines to which an ellipsized, wrapping label should be limited. The (setf gtk:label-lines) function sets the number of lines. This has no effect if the label is not wrapping or ellipsized. Set this to -1 if you do not want to limit the number of lines.
See also:
2024-4-24
Accessor gtk:label-max-width-chars (object)
Syntax:
(gtk:label-max-width-chars object) => n-chars
(setf (gtk:label-max-width-chars object) n-chars)
Arguments:
object -- a gtk:label widget
n-chars -- an integer with the desired maximum width, in characters
Details:
Accessor of the max-width-chars slot of the gtk:label class. The gtk:label-max-width-chars function returns the maximum width of the label in characters. The (setf gtk:label-max-width-chars) function sets the desired maximum width.
See also:
2024-4-24
Accessor gtk:label-mnemonic-keyval (object)
Syntax:
(gtk:label-mnemonic-keyval object) => keyval
Arguments:
object -- a gtk:label widget
keyval -- an unsigned integer with the keyval
Details:
Accessor of the mnemonic-keyval slot of the gtk:label class. If the label has been set so that it has a mnemonic key the gtk:label-mnemonic-keyval function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns #xffffff.
Examples:
(setq label (gtk:label-new-with-mnemonic "_Print"))
=> #<gtk:label {1001A051E3}>
(gtk:label-mnemonic-keyval label) => 112    
See also:
2024-4-24
Accessor gtk:label-mnemonic-widget (object)
Syntax:
(gtk:label-mnemonic-widget object) => widget
(setf (gtk:label-mnemonic-widget object) widget)
Arguments:
object -- a gtk:label widget
widget -- a gtk:widget target
Details:
Accessor of the mnemonic-widget slot of the gtk:label class. The gtk:label-mnemonic-widget function returns the target of the mnemonic of the label, or nil if none has been set and the default algorithm will be used.

If the label has been set so that it has an mnemonic key, using the gtk:label-set-markup-with-mnemonic, gtk:label-set-text-with-mnemonic, gtk:label-new-with-mnemonic functions or the use-underline property, the label can be associated with a widget that is the target of the mnemonic.

When the label is inside a widget, like a gtk:button widget or a gtk:notebook tab, it is automatically associated with the correct widget, but sometimes, for example, when the target is a gtk:entry widget next to the label, you need to set it explicitly using this function.

The target widget will be accelerated by emitting the "mnemonic-activate" signal on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise.
See also:
2024-4-24
Accessor gtk:label-natural-wrap-mode (object)
Syntax:
(gtk:label-natural-wrap-mode object) => mode
(setf (gtk:label-natural-wrap-mode object) mode)
Arguments:
object -- a gtk:label widget
mode -- a gtk:natural-wrap-mode value
Details:
Accessor of the natural-wrap-mode slot of the gtk:label class. The gtk:label-natural-wrap-mode function returns the line wrap mode used by the label. The (setf gtk:label-natural-wrap-mode) function sets the line wrap mode.

This only affects the natural size requested, for the actual wrapping used, see the wrap-mode property.

Since 4.6
See also:
2024-4-24
Accessor gtk:label-selectable (object)
Syntax:
(gtk:label-selectable object) => selectable
(setf (gtk:label-selectable object) selectable)
Arguments:
object -- a gtk:label widget
selectable -- true to allow selecting text in the label
Details:
Accessor of the selectable slot of the gtk:label class. Selectable labels allow the user to select text from the label, for copy and paste.
See also:
2024-4-24
Accessor gtk:label-single-line-mode (object)
Syntax:
(gtk:label-single-line-mode object) => mode
(setf (gtk:label-single-line-mode object) mode)
Arguments:
object -- a gtk:label widget
mode -- true if the label should be in single line mode
Details:
Accessor of the single-line-mode slot of the gtk:label class. The gtk:label-single-line-mode function returns whether the label is in single line mode. The (setf gtk:label-single-line-mode) function sets whether the label is in single line mode.
See also:
2024-4-24
Accessor gtk:label-tabs (object)
Syntax:
(gtk:label-tabs object) => tabs
(setf (gtk:label-tabs object) tabs)
Arguments:
object -- a gtk:label widget
tabs -- a pango:tab-array instance with the tabs
Details:
Accessor of the tabs slot of the gtk:label class. The gtk:label-tabs function gets the tabs for the label. The (setf gtk:label-tabs) function sets the default tab stops for paragraphs in the label.

The returned array will be nil if "standard" (8-space) tabs are used.

Since 4.8
See also:
2024-4-24
Accessor gtk:label-use-markup (object)
Syntax:
(gtk:label-use-markup object) => setting
(setf (gtk:label-use-markup object) setting)
Arguments:
object -- a gtk:label widget
setting -- true if the text of the label should be parsed for markup
Details:
Accessor of the use-markup slot of the gtk:label class. The gtk:label-use-markup function returns whether the text of the label is interpreted as marked up with the Pango text markup language. The (setf gtk:label-use-markup) function sets whether the text of the label contains markup. See the gtk:label-set-markup function.
See also:
2024-4-24
Accessor gtk:label-use-underline (object)
Syntax:
(gtk:label-use-underline object) => setting
(setf (gtk:label-use-underline object) setting)
Arguments:
object -- a gtk:label widget
setting -- true if underlines in the text indicate mnemonics
Details:
Accessor of the use-underline slot of the gtk:label class. The gtk:label-use-underline function returns whether an embedded underline in the label indicates a mnemonic. If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
See also:
2024-4-24
Accessor gtk:label-width-chars (object)
Syntax:
(gtk:label-width-chars object) => n-chars
(setf (gtk:label-width-chars object) n-chars)
Arguments:
object -- a gtk:label widget
n-chars -- an integer with the new desired width, in characters
Details:
Accessor of the width-chars slot of the gtk:label class. The gtk:label-width-chars function retrieves the desired width of the label, in characters. The (setf gtk:label-width-chars) function sets the desired width.
See also:
2024-4-24
Accessor gtk:label-wrap (object)
Syntax:
(gtk:label-wrap object) => wrap
(setf (gtk:label-wrap object) wrap)
Arguments:
object -- a gtk:label widget
wrap -- a boolean whether lines are wrapped
Details:
Accessor of the wrap slot of the gtk:label class. If set, wrap lines if the text becomes too wide.
See also:
2024-4-24
Accessor gtk:label-wrap-mode (object)
Syntax:
(gtk:label-wrap-mode object) => setting
(setf (gtk:label-wrap-mode object) setting)
Arguments:
object -- a gtk:label widget
setting -- a value of the pango:wrap-mode enumeration
Details:
Accessor of the wrap-mode slot of the gtk:label class. If line wrapping is on, see the wrap property, this controls how the line wrapping is done. The default is :word, which means wrap on word boundaries.
See also:
2024-4-24
Accessor gtk:label-xalign (object)
Syntax:
(gtk:label-xalign object) => xalign
(setf (gtk:label-xalign object) xalign)
Arguments:
object -- a gtk:label widget
xalign -- a float with the horizontal alignment, between 0.0 and 1.0
Details:
Accessor of the xalign slot of the gtk:label class. The gtk:label-xalign function sets the xalign property for the label. The (setf gtk:label-xalign) function sets the property.
See also:
2024-10-28
Accessor gtk:label-yalign (object)
Syntax:
(gtk:label-yalign object) => yalign
(setf (gtk:label-yalign object) yalign)
Arguments:
object -- a gtk:label widget
yalign -- a float with the vertical alignment, between 0.0 and 1.0
Details:
Accessor of the yalign slot of the gtk:label class. The gtk:label-yalign function sets the yalign property for the label. The (setf gtk:label-yalign) function sets property.
See also:
2024-10-28
Function gtk:label-new (&optional text)
Arguments:
text -- an optional string with the text of the label, or nil
Returns:
The new gtk:label widget.
Details:
Creates a new label with the given text inside it. You can pass nil, the default value, to get an empty label.
See also:
2024-10-28
Function gtk:label-new-with-mnemonic (text)
Arguments:
text -- a string with the text of the label, with an underscore in front of the mnemonic character
Returns:
The new gtk:label widget.
Details:
Creates a new gtk:label widget, containing the given text.

If characters in text are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using the gtk:label-mnemonic-widget function.

If the gtk:label-mnemonic-widget function is not called, then the first activatable ancestor of the gtk:label widget will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic.
See also:
2024-10-28
Function gtk:label-text (label)
Syntax:
(gtk:label-text label) => text
(setf (gtk:label-text-label) text)
Arguments:
label -- a gtk:label widget
text -- a string with the text
Details:
The gtk:label-text function fetches the text from a label, as displayed on the screen. The (setf gtk:label-text) function sets the text.

It overwrites any text that was there before. This will also clear any previously set mnemonic accelerators. This does not include any embedded underlines indicating mnemonics or Pango markup. See the gtk:label-label function.
See also:
2024-5-13
Function gtk:label-set-markup (label text)
Arguments:
label -- a gtk:label widget
text -- a markup string
Details:
Parses text which is marked up with the Pango text markup language, setting the text of the label and attribute list based on the parse results.
See also:
2024-4-24
Function gtk:label-set-text-with-mnemonic (label text)
Arguments:
label -- a gtk:label widget
text -- a string for the label
Details:
Sets the text of the label from the string text. If characters in text are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using the gtk:label-mnemonic-widget function.
See also:
2024-4-24
Function gtk:label-set-markup-with-mnemonic (label text)
Arguments:
label -- a gtk:label widget
text -- a Pango markup string
Details:
Parses text which is marked up with the Pango text markup language. This sets the text and attribute list of the label based on the parse results.

If characters in text are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using the gtk:label-mnemonic-widget function.
See also:
2024-4-24
Function gtk:label-layout (label)
Arguments:
label -- a gtk:label widget
Returns:
The pango:layout object for this label.
Details:
Gets the Pango layout used to display the label. The layout is useful, for example, to convert text positions to pixel positions, in combination with the gtk:label-layout-offsets function. The label is free to recreate its layout at any time, so it should be considered read-only.
See also:
2024-10-28
Function gtk:label-layout-offsets (label)
Arguments:
label -- a gtk:label widget
Returns:
x -- an integer with the x offset
y -- an integer with the y offset
Details:
Obtains the coordinates where the label will draw the pango:layout object representing the text in the label. This is useful to convert mouse events into coordinates inside the pango:layout object, for example, to take some action if some part of the label is clicked. Remember when using the pango:layout functions you need to convert to and from pixels using the pango:pixels function or the pango:+scale+ constant.
Examples:
(gtk:label-layout-offsets (gtk:label-new))
=> 0
=> -9
(gtk:label-layout-offsets (gtk:label-new "text"))
=> -14
=> -9    
See also:
2024-10-28
Function gtk:label-select-region (label start end)
Arguments:
label -- a gtk:label widget
start -- an integer with the start offset, in characters not bytes
end -- an integer with the end offset, in characters not bytes
Details:
Selects a range of characters in the label, if the label is selectable. See the gtk:label-selectable function. If the label is not selectable, this function has no effect. If start or end are -1, then the end of the label will be substituted.
See also:
2024-4-24
Function gtk:label-selection-bounds (label)
Arguments:
label -- a gtk:label widget
Returns:
start -- an integer with the start of the selection, as a character offset
end -- an integer with the end of the selection, as a character offset
Details:
Gets the selected range of characters in the label.
See also:
2024-4-24
Function gtk:label-current-uri (label)
Arguments:
label -- a gtk:label widget
Returns:
The string with the currently active URI.
Details:
Returns the URI for the currently active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently positioned.

This function is intended for use in a "activate-link" signal handler or for use in a "query-tooltip" signal handler.
See also:
2024-10-28

GtkInscription

GEnum gtk:inscription-overflow
Declaration:
(gobject:define-genum "GtkInscriptionOverflow" inscription-overflow
  (:export t
   :type-initializer "gtk_inscription_overflow_get_type")
  (:clip 0)
  (:ellipsize-start 1)
  (:ellipsize-middle 2)
  (:ellipsize-end 3))  
Values:
:clip
Clip the remaining text.
:ellipsize-start
Omit characters at the start of the text.
:ellipsize-middle
Omit characters at the middle of the text.
:ellipsize-end
Omit characters at the end of the text.
Details:
The different methods to handle text in the gtk:inscription widget when it does not fit the available space.

Since 4.8
See also:
2024-4-25
Class gtk:inscription
Superclasses:
Documented Subclasses:
None
Direct Slots:
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of style attributes to apply to the text of the inscription.
markup
The markup property of type :string (Write)
Utility property that sets both the text and attributes properties, mainly intended for use in gtk:builder UI files to ease translation support and bindings. This function uses the pango:parse-markup function to parse the markup into text and attributes. The markup must be valid. If you cannot ensure that, consider using the pango:parse-markup function and setting the two properties yourself.
min-chars
The min-chars property of type :uint (Read / Write)
The number of characters that should fit into the inscription at minimum. This influences the requested width, not the width actually given to the widget, which might turn out to be larger. Note that this is an approximate character width, so some characters might be wider and some might be thinner, so do not expect the number of characters to exactly match. If you set this property to 0, the inscription will not request any width at all and its width will be determined entirely by its surroundings.
Default value: 3
min-lines
The min-lines property of type :uint (Read / Write)
The number of lines that should fit into the inscription at minimum. This influences the requested height, not the height actually given to the widget, which might turn out to be larger. Note that this is an approximate line height, so if the text uses things like fancy Unicode or attribute that influence the height, the text might not fit. If you set this property to 0, the inscription will not request any height at all and its height will be determined entirely by its surroundings.
Default value: 1
nat-chars
The nat-chars property of type :uint (Read / Write)
The number of characters that should ideally fit into the inscription. This influences the requested width, not the width actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than the min-chars property, that value will be used. In particular, for the default value of 0, this will always be the case.
Default value: 0
nat-lines
The nat-lines property of type :uint (Read / Write)
The number of lines that should ideally fit into the inscription. This influences the requested height, not the height actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than the min-lines property, that value will be used. In particular, for the default value of 0, this will always be the case.
Default value: 0
text
The text property of type :string (Read / Write)
The displayed text.
Default value: nil
text-overflow
The text-overflow property of type gtk:inscription-overflow (Read / Write)
The overflow method to use for the text.
Default value: :clip
wrap-mode
The wrap-mode property of type pango:wrap-mode (Read / Write)
Controls how the line wrapping is done. Note that unlike the gtk:label widget, the default here is the :word-char value.
Default value: :word-char
xalign
The xalign property of type :float (Read / Write)
The horizontal alignment of the text inside the allocated size. Compare this to the halign property, which determines how the size allocation of the inscription is positioned in the available space.
Allowed values: [0.0, 1.0]
Default value: 0.0
yalign
The yalign property of type :float (Read / Write)
The vertical alignment of the text inside the allocated size. Compare this to the valign property, which determines how the size allocation of the inscription is positioned in the available space.
Allowed values: [0.0, 1.0]
Default value: 0.5
Returned by:
Slot Access Functions:
Details:
The gtk:inscription widget is a widget to show text in a predefined area. You likely want to use the gtk:label widget instead as this widget is intended only for a small subset of use cases. The main scenario envisaged is inside lists such as the gtk:column-view widget.

While a gtk:label widget sizes itself depending on the text that is displayed, the gtk:inscription widget is given a size and inscribes the given text into that space as well as it can.

Users of this widget should take care to plan behaviour for the common case where the text does not fit exactly in the allocated space.

Since 4.8
See also:
2024-10-28
Accessor gtk:inscription-attributes (object)
Syntax:
(gtk:inscription-attributes object) => attrs
(setf (gtk:inscription-attributes object) attrs)
Arguments:
object -- a gtk:inscription widget
attrs -- a pango:attr-list instance
Details:
Accessor of the attributes slot of the gtk:inscription class. The gtk:inscription-attributes function gets the attribute list of the inscription. The (setf gtk:inscription-attributes) function applies attributes to the inscription text. These attributes will not be evaluated for sizing the inscription.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-markup (object)
Syntax:
(setf (gtk:inscription-markup object) attrs)
Arguments:
object -- a gtk:inscription widget
markup -- a string with the markup to display
Details:
Accessor of the markup slot of the gtk:inscription class. The (setf gtk:inscription-markup) function is an utility function to set the text and attributes to be displayed.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-min-chars (object)
Syntax:
(gtk:inscription-min-chars object) => chars
(setf (gtk:inscription-min-chars object) chars)
Arguments:
object -- a gtk:inscription widget
chars -- an integer with the minimum number of characters that should fit, approximately
Details:
Accessor of the min-chars slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-min-lines (object)
Syntax:
(gtk:inscription-min-lines object) => lines
(setf (gtk:inscription-min-lines object) lines)
Arguments:
object -- a gtk:inscription widget
lines -- an integer with the minimum number of lines that should fit, approximately
Details:
Accessor of the min-lines slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-nat-chars (object)
Syntax:
(gtk:inscription-nat-chars object) => chars
(setf (gtk:inscription-nat-chars object) chars)
Arguments:
object -- a gtk:inscription widget
chars -- an integer with the number of characters that should ideally fit
Details:
Accessor of the nat-chars slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-nat-lines (object)
Syntax:
(gtk:inscription-nat-lines object) => lines
(setf (gtk:inscription-nat-lines object) lines)
Arguments:
object -- a gtk:inscription widget
lines -- an integer with the number of lines that should ideally fit
Details:
Accessor of the nat-lines slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-text (object)
Syntax:
(gtk:inscription-text object) => text
(setf (gtk:inscription-text object) text)
Arguments:
object -- a gtk:inscription widget
lines -- a string with the text to display
Details:
Accessor of the text slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-text-overflow (object)
Syntax:
(gtk:inscription-text-overflow object) => setting
(setf (gtk:inscription-text-overflow object) setting)
Arguments:
object -- a gtk:inscription widget
setting -- a gtk:inscription-overflow value
Details:
Accessor of the text-overflow slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-wrap-mode (object)
Syntax:
(gtk:inscription-wrap-mode object) => mode
(setf (gtk:inscription-wrap-mode object) mode)
Arguments:
object -- a gtk:inscription widget
mode -- a pango:wrap-mode value
Details:
Accessor of the wrap-mode slot of the gtk:inscription class.

Since 4.8
See also:
2024-4-25
Accessor gtk:inscription-xalign (object)
Syntax:
(gtk:inscription-xalign object) => xalign
(setf (gtk:inscription-xalign object) xalign)
Arguments:
object -- a gtk:inscription widget
xalign -- a single float with the xalign value, between 0.0 and 1.0
Details:
Accessor of the xalign slot of the gtk:inscription class.

Since 4.8
See also:
2024-10-28
Accessor gtk:inscription-yalign (object)
Syntax:
(gtk:inscription-yalign object) => yalign
(setf (gtk:inscription-yalign object) yalign)
Arguments:
object -- a gtk:inscription widget
yalign -- a single float with the yalign value, between 0.0 and 1.0
Details:
Accessor of the yalign slot of the gtk:inscription class.

Since 4.8
See also:
2024-10-28
Function gtk:inscription-new (&optional text)
Arguments:
text -- an optional string with the text to display, or nil
Returns:
The new gtk:inscription widget.
Details:
Creates a new gtk:inscription widget with the given text. You can pass nil, the default value, to an empty inscription.

Since 4.8
See also:
2024-10-28

GtkImage

GEnum gtk:image-type
Declaration:
(gobject:define-genum "GtkImageType" image-type
  (:export t
   :type-initializer "gtk_image_type_get_type")
  (:empty 0)
  (:icon-name 1)
  (:gicon 2)
  (:paintable 3))  
Values:
:empty
There is no image displayed by the widget.
:icon-name
The widget contains a named icon.
:gicon
The widget contains a g:icon object.
:paintable
The widget contains a gdk:paintable object.
Details:
Describes the image data representation used by a gtk:image widget. If you want to get the image from the widget, you can only get the currently stored representation. For example, if the gtk:image-storage-type function returns the :paintable value, then you can call the gtk:image-paintable function. For empty images, you can request any storage type, but they will all return nil values.
See also:
2024-4-25
Class gtk:image
Superclasses:
Documented Subclasses:
None
Direct Slots:
file
The file property of type :string (Read / Write)
The name of the file to load and display.
Default value: nil
gicon
The gicon property of type g:icon (Read / Write)
The icon displayed in the image. For themed icons, if the icon theme is changed, the image will be updated automatically.
icon-name
The icon-name property of type :string (Read / Write)
The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.
Default value: nil
icon-size
The icon-size property of type gtk:icon-size (Read / Write)
The symbolic size to display icons at.
Default value: :inherit
paintable
The paintable property of type gdk:paintable (Read / Write)
The paintable to display.
pixel-size
The pixel-size property of type :int (Read / Write)
Can be used to specify a fixed size overriding the icon-size property for images of :icon-name type.
Allowed values: >= -1
Default value: -1
resource
The resource property of type :string (Read / Write)
The path to a resource file to display.
Default value: nil
storage-type
The storage-type property of type gtk:image-type (Read)
The representation being used for image data.
Default value: :empty
use-fallback
The use-fallback property of type :boolean (Read / Write)
Whether the icon displayed in the image will use standard icon names fallback. The value of this property is only relevant for images of :icon-name and :gicon type.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:image widget displays an image. Various kinds of objects can be displayed as an image. Most typically, you would load a gdk:texture object from a file, and then display that.

Figure: GtkImage

There is a convenience gtk:image-new-from-file function to do this, used as follows:
(let ((image (gtk:image-new-from-file "myfile.png")))
  ... )  
If the file is not loaded successfully, the image will contain a "broken image" icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with the gdk:texture-new-from-file function, then create the gtk:image widget with the gtk:image-new-from-paintable function.

Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of the g:resource API for details. In this case, the resource property, the gtk:image-new-from-resource and gtk:image-set-from-resource functions should be used.

The gtk:image widget displays its image as an icon, with a size that is determined by the application. See the gtk:picture widget if you want to show an image at is actual size.
CSS nodes:
The gtk:image implementation has a single CSS node with the name image. The .normal-icons or .large-icons style classes may appear, depending on the icon-size property.
Accessibility:
The gtk:image implementation uses the :img role of the gtk:accessible-role enumeration.
See also:
2024-10-29
Accessor gtk:image-file (object)
Syntax:
(gtk:image-file object) => filename
(setf (gtk:image-file object) filename)
Arguments:
object -- a gtk:image widget
filename -- a string with the name of the file to load and display
Details:
Accessor of the file slot of the gtk:image class. The name of the file to load and display.
See also:
2024-4-25
Accessor gtk:image-gicon (object)
Syntax:
(gtk:image-gicon object) => gicon
(setf (gtk:image-gicon object) gicon)
Arguments:
object -- a gtk:image widget
gicon -- a g:icon icon
Details:
Accessor of the gicon slot of the gtk:image class. The icon displayed in the image. For themed icons, if the icon theme is changed, the image will be updated automatically.
See also:
2024-4-25
Accessor gtk:image-icon-name (object)
Syntax:
(gtk:image-icon-name object) => name
(setf (gtk:image-icon-name object) name)
Arguments:
object -- a gtk:image widget
name -- a string with the name of the icon
Details:
Accessor of the icon-name slot of the gtk:image class. The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.
See also:
2024-4-26
Accessor gtk:image-icon-size (object)
Syntax:
(gtk:image-icon-size object) => size
(setf (gtk:image-icon-size object) size)
Arguments:
object -- a gtk:image widget
size -- a gtk:icon-size value
Details:
Accessor of the icon-size slot of the gtk:image class. The symbolic size to display icons at.
See also:
2024-10-29
Accessor gtk:image-paintable (object)
Syntax:
(gtk:image-paintable object) => paintable
(setf (gtk:image-paintable object) paintable)
Arguments:
object -- a gtk:image widget
paintable -- a gdk:paintable object
Details:
Accessor of the paintable slot of the gtk:image class. The gtk:image-paintable function gets the paintable being displayed by the image. The (setf gtk:image-paintable) function sets the paintable.

The gtk:image-type storage type of the image must be :empty or :paintable, see the gtk:image-storage-type function.
See also:
2024-4-25
Accessor gtk:image-pixel-size (object)
Syntax:
(gtk:image-pixel-size object) => size
(setf (gtk:image-pixel-size object) size)
Arguments:
object -- a gtk:image widget
size -- an integer with the new pixel size
Details:
Accessor of the pixel-size slot of the gtk:image class. The gtk:image-pixel-size function gets the pixel size used for named icons. The (setf gtk:image-pixel-size) function sets the pixel size. If the pixel size is set to a value not equal to -1, it is used instead of the icon-size property.
See also:
2024-10-29
Accessor gtk:image-resource (object)
Syntax:
(gtk:image-resource object) => path
(setf (gtk:image-resource object) path)
Arguments:
object -- a gtk:image widget
path -- a string with a resource path
Details:
Accessor of the resource slot of the gtk:image class. A path to a resource file to display.
See also:
2024-4-25
Accessor gtk:image-storage-type (object)
Syntax:
(gtk:image-storage-type object) => type
(setf (gtk:image-storage-type object) type)
Arguments:
object -- a gtk:image widget
type -- a value of the gtk:image-type enumeration
Details:
Accessor of the storage-type slot of the gtk:image class. The gtk:image-storage-type function gets the type of representation being used by the gtk:image widget to store image data. The (setf gtk:image-storage-type) function sets the image type.

If the gtk:image widget has no image data, the return value will be :empty.
See also:
2024-4-25
Accessor gtk:image-use-fallback (object)
Syntax:
(gtk:image-use-fallback object) => setting
(setf (gtk:image-use-fallback object) setting)
Arguments:
object -- a gtk:image widget
setting -- a boolean whether to use standard icon names fallback
Details:
Accessor of the use-fallback slot of the gtk:image class. Whether the icon displayed in the gtk:image widget will use standard icon names fallback. The value of this property is only relevant for images of :icon-name and :gicon type.
See also:
2024-4-25
Function gtk:image-new ()
Returns:
The newly created gtk:image widget.
Details:
Creates a new empty image.
See also:
2024-4-25
Function gtk:image-new-from-file (path)
Arguments:
path -- a pathname or namestring for the name of the file
Returns:
The new gtk:image widget.
Details:
Creates a new image displaying the file path. This function always returns a valid gtk:image widget. If the file is not found or cannot be loaded, the resulting gtk:image widget will display a "broken image" icon.

If you need to detect failures to load the file, use the gdk:texture-new-from-file function to load the file yourself, then create the gtk:image widget from the texture.

The storage type, see the gtk:image-storage-type function, of the returned image is not defined, it will be whatever is appropriate for displaying the file.
See also:
2025-3-2
Function gtk:image-new-from-resource (resource)
Arguments:
resource -- a string with a resource path
Returns:
The new gtk:image widget.
Details:
Creates an image displaying the resource file in resource. This function always returns a valid gtk:image widget. If the file is not found or can not be loaded, the resulting gtk:image widget will display a "broken image" icon.

If you need to detect failures to load the file, use the gdk-pixbuf:pixbuf-new-from-resource function to load the file yourself, then create the gtk:image widget from the pixbuf, or for animations, use the gdk-pixbuf:pixbuf-animation-new-from-resource function.

The storage type, see the gtk:image-storage-type function, of the returned image is not defined, it will be whatever is appropriate for displaying the file.
See also:
2024-10-29
Function gtk:image-new-from-pixbuf (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
Returns:
The new gtk:image widget.
Details:
Creates an image displaying pixbuf. Note that this function just creates an image from the pixbuf. The image created will not react to state changes. Should you want that, you should use the gtk:image-new-from-icon-name function.
Warning:
This function is deprecated since 4.12. Use the gtk:image-new-from-paintable and gdk:texture-new-for-pixbuf functions instead.
See also:
2024-4-25
Function gtk:image-new-from-paintable (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The new gtk:image widget.
Details:
Creates a new image displaying the paintable. The image will track changes to the paintable and update its size and contents in response to it.
See also:
2024-4-25
Function gtk:image-new-from-icon-name (name)
Arguments:
name -- a string with an icon name
Returns:
The new gtk:image widget displaying the themed icon.
Details:
Creates an image displaying an icon from the current icon theme. If the icon name is not known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.
See also:
2024-4-25
Function gtk:image-new-from-gicon (icon)
Arguments:
icon -- a g:icon object
Returns:
The new gtk:image widget displaying the themed icon.
Details:
Creates an image displaying an icon from the current icon theme. If the icon name is not known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.
See also:
2024-4-25
Function gtk:image-clear (image)
Arguments:
image -- a gtk:image widget
Details:
Resets the image to be empty.
See also:
2024-6-30
Function gtk:image-set-from-file (image file)
Arguments:
image -- a gtk:image widget
file -- a pathname or namestring for the file to load
Details:
Sets the image to display file. See the gtk:image-new-from-file function for details.
See also:
2024-10-29
Function gtk:image-set-from-resource (image resource)
Arguments:
image -- a gtk:image widget
resource -- a string with a resource path
Details:
Sets the image to display resource. See the gtk:image-new-from-resource function for details.
See also:
2024-6-30
Function gtk:image-set-from-pixbuf (image pixbuf)
Arguments:
image -- a gtk:image widget
pixbuf -- a gdk-pixbuf:pixbuf object
Details:
Sets the image to display pixbuf.
Warning:
This function is deprecated since 4.12. Use the gtk:image-set-from-paintable function instead.
See also:
2024-10-29
Function gtk:image-set-from-paintable (image paintable)
Arguments:
image -- a gtk:image widget
paintable -- a gdk:paintable object
Details:
Sets the image to display paintable. See the gtk:image-new-from-paintable function for more details.
See also:
2024-6-30
Function gtk:image-set-from-icon-name (image name)
Arguments:
image -- a gtk:image widget
name -- a string with an icon name
Details:
Sets the image to display name. See the gtk:image-new-from-icon-name function for details.
See also:
2024-6-30
Function gtk:image-set-from-gicon (image icon)
Arguments:
image -- a gtk:image widget
icon -- a g:icon object with the themed icon
Details:
Sets the image to display the themed icon. See the gtk:image-new-from-gicon function for details.
See also:
2023-11-4

GtkPicture

GEnum gtk:content-fit
Declaration:
(gobject:define-genum "GtkContentFit" content-fit
  (:export t
   :type-initializer "gtk_content_fit_get_type")
  (:fill 0)
  (:contain 1)
  (:cover 2)
  (:scale-down 3))  
Values:
:fill
Make the content fill the entire allocation, without taking its aspect ratio in consideration. The resulting content will appear as stretched if its aspect ratio is different from the allocation aspect ratio.
:contain
Scale the content to fit the allocation, while taking its aspect ratio in consideration. The resulting content will appear as letterboxed if its aspect ratio is different from the allocation aspect ratio.
:cover
Cover the entire allocation, while taking the content aspect ratio in consideration. The resulting content will appear as clipped if its aspect ratio is different from the allocation aspect ratio.
:scale-down
The content is scaled down to fit the allocation, if needed, otherwise its original size is used.
Details:
Controls how a content should be made to fit inside an allocation. Since 4.8
See also:
2024-10-13
Class gtk:picture
Superclasses:
Documented Subclasses:
None
Direct Slots:
alternative-text
The alternative-text property of type :string (Read / Write)
The alternative textual description for the picture.
Default value: nil
can-shrink
The can-shrink property of type :boolean (Read / Write)
Whether the picture can be made smaller than the natural size of its contents.
Default value: true
content-fit
The content-fit property of type gtk:content-fit (Read / Write)
How the content should be resized to fit inside the picture. Since 4.8
Default value: :contain
file
The file property of type g:file (Read / Write)
The file that is displayed or nil if none.
Default value: nil
keep-aspect-ratio
The keep-aspect-ratio property of type :boolean (Read / Write)
Whether the picture will render its contents trying to preserve the aspect ratio of the contents. Deprecated since 4.8, use the content-fit property instead.
Default value: true
paintable
The paintable property of type gdk:paintable (Read / Write)
The paintable to be displayed by the picture.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:picture widget displays a gdk:paintable object.

Figure: GtkPicture

Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display that, there is a convenience function to do this:
(let ((picture (gtk:picture-new-for-filename "myfile.png")))
   ... )  
If the file is not loaded successfully, the picture will contain a "broken image" icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with the gdk:texture-new-from-file function, then create the gtk:picture widget with the gtk:picture-new-for-paintable function.

Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of the g:resource API for details. In this case, the gtk:picture-new-for-resource and gtk:picture-set-resource functions should be used.

Sizing the paintable
You can influence how the paintable is displayed inside the gtk:picture widget by changing the content-fit property. See the gtk:content-fit enumeration for details. The can-shrink property can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use, like when displaying user-loaded images. This can easily cause the picture to grow larger than the screen. The halign and valign properties can be used to make sure the paintable does not fill all available space but is instead displayed at its original size.
CSS nodes:
The gtk:picture implementation has a single CSS node with the name picture.
Accessibility:
The gtk:picture implementation uses the :img role of the gtk:accessible-role enumeration.
See also:
2024-10-13
Accessor gtk:picture-alternative-text (object)
Syntax:
(gtk:picture-alternative-text object) => text
(setf (gtk:picture-alternative-text object) text)
Arguments:
object -- a gtk:picture widget
text -- a string with the alternative textual description for the picture
Details:
Accessor of the alternative-text slot of the gtk:picture class. The gtk:picture-alternative-text function gets the alternative textual description of the picture or returns nil if the picture cannot be described textually. The (setf gtk:picture-alternative-text) function sets an alternative textual description. It is equivalent to the "alt" attribute for images on websites. This text will be made available to accessibility tools.
See also:
2024-10-13
Accessor gtk:picture-can-shrink (object)
Syntax:
(gtk:picture-can-shrink object) => setting
(setf (gtk:picture-can-shrink object) setting)
Arguments:
object -- a gtk:picture widget
setting -- a boolean whether the picture can be made smaller than it contents
Details:
Accessor of the can-shrink slot of the gtk:picture class. If set to the true value, the picture can be made smaller than its contents. The contents will then be scaled down when rendering. If you want to still force a minimum size manually, consider using the gtk:widget-size-request function. Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via the halign and valign properties.
See also:
2024-10-30
Accessor gtk:picture-content-fit (object)
Syntax:
(gtk:picture-content-fit object) => setting
(setf (gtk:picture-content-fit object) setting)
Arguments:
object -- a gtk:picture widget
setting -- a gtk:content-fit value
Details:
Accessor of the content-fit slot of the gtk:picture class. The gtk:picture-content-fit function returns the fit mode for the content of the picture. The (setf gtk:picture-content-fit) function sets how the content should be resized to fit the picture.

Since 4.8
See also:
2024-10-13
Accessor gtk:picture-file (object)
Syntax:
(gtk:picture-file object) => file
(setf (gtk:picture-file object) file)
Arguments:
object -- a gtk:picture widget
file -- a g:file object that is displayed or nil if none
Details:
Accessor of the file slot of the gtk:picture class. The gtk:picture-file function gets the file currently displayed if the picture is displaying a file. If the picture is not displaying a file, for example when the gtk:picture-paintable function was used, then nil is returned. The (setf gtk:picture-file) function makes the picture load and display file. See the gtk:picture-new-for-file documentation for more details.
See also:
2024-10-13
Accessor gtk:picture-keep-aspect-ratio (object)
Syntax:
(gtk:picture-keep-aspect-ratio object) => setting
(setf (gtk:picture-keep-aspect-ratio object) setting)
Arguments:
object -- a gtk:picture widget
setting -- a boolean whether the picture will render its contents trying to preserve the aspect ratio of the contents
Details:
Accessor of the keep-aspect-ratio slot of the gtk:picture class. If set to the true value, the picture will render its contents according to its aspect ratio. That means that empty space may show up at the top/bottom or left/right of the picture. If set to the false value or if the contents provide no aspect ratio, the contents will be stretched over the whole area of the picture.
Warning:
This function is deprecated since 4.8. Use the content-fit property instead.
See also:
2024-10-13
Accessor gtk:picture-paintable (object)
Syntax:
(gtk:picture-keep-paintable object) => paintable
(setf (gtk:picture-paintable object) paintable)
Arguments:
object -- a gtk:picture widget
paintable -- a gdk:paintable object or nil
Details:
Accessor of the paintable slot of the gtk:picture class. The gtk:picture-paintable function gets the paintable being displayed by the picture. The (setf gtk:picture-paintable) function makes the picture display the given paintable. If the paintable is nil, nothing will be displayed. See the gtk:picture-new-for-paintable documentation for more details.
See also:
2024-10-13
Function gtk:picture-new ()
Returns:
The newly created gtk:picture widget.
Details:
Creates a new empty picture.
See also:
2024-10-13
Function gtk:picture-new-for-paintable (paintable)
Arguments:
paintable -- a gdk:paintable object, or nil
Returns:
The new gtk:picture widget.
Details:
Creates a new picture displaying paintable. The gtk:picture widget will track changes to the paintable and update its size and contents in response to it.
See also:
2024-10-13
Function gtk:picture-new-for-pixbuf (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object, or nil
Returns:
The new gtk:picture widget
Details:
Creates a new picture displaying pixbuf. This is a utility function that calls the gtk:picture-new-for-paintable function. See that function for details. The pixbuf must not be modified after passing it to this function.
Warning:
This function is deprecated since 4.12. Use the gtk:picture-new-for-paintable and gdk:texture-new-for-pixbuf functions instead.
See also:
2024-10-13
Function gtk:picture-new-for-file (file)
Arguments:
file -- a g:file object
Returns:
The new gtk:picture widget.
Details:
Creates a new picture displaying the given file. If the file is not found or cannot be loaded, the resulting picture is empty.

If you need to detect failures to load the file, use the gdk:texture-new-from-file function to load the file yourself, then create the picture from the texture.
See also:
2024-10-13
Function gtk:picture-new-for-filename (filename)
Arguments:
filename -- a pathname or namestring for the file
Returns:
The new gtk:picture widget.
Details:
Creates a new picture displaying the file filename. This is a utility function that calls the gtk:picture-new-for-file function. See that function for details.
See also:
2024-10-13
Function gtk:picture-new-for-resource (path)
Arguments:
path -- a string with the resource path
Returns:
The new gtk:picture widget.
Details:
Creates a new picture displaying the resource at path. This is a utility function that calls the gtk:picture-new-for-file function. See that function for details.
See also:
2024-10-13
Function gtk:picture-set-pixbuf (picture pixbuf)
Arguments:
picture -- a gtk:picture widget
pixbuf -- a gdk-pixbuf:pixbuf object, or nil
Details:
See the gtk:picture-new-for-pixbuf function for details. This is a utility function that calls the gtk:picture-paintable function.
Warning:
This function is deprecated since 4.12. Use the gtk:picture-paintable function instead.
See also:
2024-10-13
Function gtk:picture-set-filename (picture filename)
Arguments:
picture -- a gtk:picture widget
filename -- a pathname or namestring with the filename
Details:
Makes the picture load and display the given filename. This is a utility function that calls the gtk:picture-file function.
See also:
2024-10-13
Function gtk:picture-set-resource (picture path)
Arguments:
picture -- a gtk:picture widget
path -- a string with the resource path
Details:
Makes the picture load and display the resource at the given resource path. This is a utility function that calls the gtk:picture-file function.
See also:
2024-10-13

GtkSpinner

Class gtk:spinner
Superclasses:
Documented Subclasses:
None
Direct Slots:
spinning
The spinning property of type :boolean (Read / Write)
Whether the spinner is spinning.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:spinner widget displays an icon size spinning animation.

Figure: GtkSpinner

It is often used as an alternative to the gtk:progress-bar widget for displaying indefinite activity, instead of actual progress.

To start the animation, use the gtk:spinner-start function, to stop it use the gtk:spinner-stop function.
CSS nodes:
The gtk:spinner implementation has a single CSS node with the name spinner. When the animation is active, the :checked pseudoclass is added to this node.
See also:
2024-4-25
Accessor gtk:spinner-spinning (object)
Syntax:
(gtk:spinner-spinning object) => spinning
(setf (gtk:spinner-spinning object) spinning)
Arguments:
object -- a gtk:spinner widget
spinning -- a boolean whether the spinner is spinning
Details:
Accessor of the spinning slot of the gtk:spinner class. The gtk:spinner-spinning function returns whether the spinner is spinning. The (setf gtk:spinner-spinning) function sets the activity of the spinner.
See also:
2024-4-25
Function gtk:spinner-new ()
Returns:
The new gtk:spinner widget.
Details:
Returns a new spinner. Not yet started.
See also:
2024-4-25
Function gtk:spinner-start (spinner)
Arguments:
spinner -- a gtk:spinner widget
Details:
Starts the animation of the spinner.
See also:
2023-8-24
Function gtk:spinner-stop (spinner)
Arguments:
spinner -- a gtk:spinner widget
Details:
Stops the animation of the spinner.
See also:
2023-8-24

GtkProgressBar

Class gtk:progress-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
ellipsize
The ellipsize property of type pango:ellipsize-mode (Read / Write)
The preferred place to ellipsize the string, if the progress bar does not have enough room to display the entire string, specified as a value of the pango:ellipsize-mode enumeration. Note that setting this property to a value other than :none has the side-effect that the progress bar requests only enough space to display the ellipsis ("..."). Another means to set the width of the progress bar is the gtk:widget-size-request function.
Default value: :none
fraction
The fraction property of type :double (Read / Write)
The fraction of total work that has been completed.
Allowed values: [0.0, 1.0]
Default value: 0.0
inverted
The inverted property of type :boolean (Read / Write)
Invert the direction in which the progress bar grows.
Default value: false
pulse-step
The pulse-step property of type :double (Read / Write)
The fraction of total progress to move the bouncing block when pulsed.
Allowed values: [0.0, 1.0]
Default value: 0.1
show-text
The show-text property of type :boolean (Read / Write)
Sets whether the progress bar will show text superimposed over the progress bar. The shown text is either the value of the text property or, if that is nil, the fraction value, as a percentage. To make a progress bar that is styled and sized suitably for containing text, even if the actual text is blank, set the show-text property to true and the text property to the empty string, not nil.
Default value: false
text
The text property of type :string (Read / Write)
Text to be displayed in the progress bar.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:progress-bar widget is typically used to display the progress of a long running operation. It provides a visual clue that processing is underway. The gtk:progress-bar widget can be used in two different modes: percentage mode and activity mode.

Figure: GtkProgressBar

When an application can determine how much work needs to take place, for example, read a fixed number of bytes from a file, and can monitor its progress, it can use the progress bar in percentage mode and the user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the application is required to call the gtk:progress-bar-fraction function periodically to update the progress bar.

When an application has no accurate way of knowing the amount of work to do, it can use the progress bar in activity mode, which shows activity by a block moving back and forth within the progress area. In this mode, the application is required to call the gtk:progress-bar-pulse function periodically to update the progress bar.

There is quite a bit of flexibility provided to control the appearance of the progress bar. Functions are provided to control the orientation of the progress bar, optional text can be displayed along with the progress bar, and the step size used in activity mode can be set.
CSS nodes:
progressbar[.osd]
├── [text]
╰── trough[.empty][.full]
      ╰── progress[.pulse]    
The gtk:progress-bar implementation has a main CSS node with name progressbar and subnodes with names text and trough, of which the latter has a subnode named progress. The text subnode is only present if text is shown. The progress subnode has the .pulse style class when in activity mode. It gets the .left, .right, .top or .bottom style classes added when the progress 'touches' the corresponding end of the progress bar. The .osd style class on the progress bar node is for use in overlays like the one Epiphany has for page loading progress.
Accessibility:
The gtk:progress-bar implementation uses the :progress-bar role of the gtk:accessible-role enumeration.
See also:
2024-10-31
Accessor gtk:progress-bar-ellipsize (object)
Syntax:
(gtk:progress-bar-ellipsize object) => mode
(setf (gtk:progress-bar-ellipsize object) mode)
Arguments:
object -- a gtk:progress-bar widget
mode -- a value of the pango:ellipsize-mode enumeration
Details:
Accessor of the ellipsize slot of the gtk:progress-bar class. The gtk:progress-bar-ellipsize function returns the ellipsizing position of the progress bar. The (setf gtk:progress-bar-ellipsize) function sets the mode used to ellipsize the text if there is not enough space to render the entire string.
See also:
2024-4-25
Accessor gtk:progress-bar-fraction (object)
Syntax:
(gtk:progress-bar-fraction object) => fraction
(setf (gtk:progress-bar-fraction object) fraction)
Arguments:
object -- a gtk:progress-bar widget
fraction -- a double float with the fraction of the task that is been completed
Details:
Accessor of the fraction slot of the gtk:progress-bar class. The gtk:progress-bar-fraction function returns the current fraction from 0.0 to 1.0 of the task that is been completed. The (setf gtk:progress-bar-fraction) function causes the progress bar to "fill in" the given fraction of the progress bar. The fraction should be between 0.0 and 1.0, inclusive.
See also:
2024-10-31
Accessor gtk:progress-bar-inverted (object)
Syntax:
(gtk:progress-bar-inverted object) => inverted
(setf (gtk:progress-bar-inverted object) inverted)
Arguments:
object -- a gtk:progress-bar widget
inverted -- true to invert the progress bar
Details:
Accessor of the inverted slot of the gtk:progress-bar class. Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction.
See also:
2024-4-25
Accessor gtk:progress-bar-pulse-step (object)
Syntax:
(gtk:progress-bar-pulse-step object) => step
(setf (gtk:progress-bar-pulse-step object) step)
Arguments:
object -- a gtk:progress-bar widget
step -- a double float with the fraction between 0.0 and 1.0
Details:
Accessor of the pulse-step slot of the gtk:progress-bar class. The gtk:progress-bar-pulse-step function retrieves the pulse step which is a fraction from 0.0 to 1.0. The (setf gtk:progress-bar-pulse-step) function sets the fraction of total progress bar length to move the bouncing block for each call to the gtk:progress-bar-pulse function.
See also:
2024-10-31
Accessor gtk:progress-bar-show-text (object)
Syntax:
(gtk:progress-bar-show-text object) => setting
(setf (gtk:progress-bar-show-text object) setting)
Arguments:
object -- a gtk:progress-bar widget
setting -- a boolean whether to show superimposed text
Details:
Accessor of the show-text slot of the gtk:progress-bar class. The gtk:progress-bar-show-text function gets the value of the show-text property. The (setf gtk:progress-bar-show-text) function sets whether the progress bar will show text superimposed over the progress bar. The shown text is either the value of the text property or, if that is nil, the fraction value, as a percentage.

To make a progress bar that is styled and sized suitably for containing text, even if the actual text is blank, set the show-text property to true and the text property to the empty string, not nil.
See also:
2024-10-31
Accessor gtk:progress-bar-text (object)
Syntax:
(gtk:progress-bar-text object) => text
(setf (gtk:progress-bar-text object) text)
Arguments:
object -- a gtk:progress-bar widget
text -- a UTF-8 string
Details:
Accessor of the text slot of the gtk:progress-bar class. The gtk:progress-bar-text function retrieves the text displayed superimposed on the progress bar, if any, otherwise nil. The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in the progress bar. The (setf gtk:progress-bar-text) function causes the given text to appear superimposed on the progress bar.

If the text argument is nil and the show-text property is true, the current value of the fraction property will be displayed as a percentage.

If the text argument is non-nil and the show-text property is true, the text will be displayed. In this case, it will not display the progress percentage. If text is the empty string, the progress bar will still be styled and sized suitably for containing text, as long as the show-text property is true.
See also:
2024-4-25
Function gtk:progress-bar-new ()
Returns:
The new gtk:progress-bar widget.
Details:
Creates a new progress bar.
See also:
2024-10-31
Function gtk:progress-bar-pulse (bar)
Arguments:
bar -- a gtk:progress-bar widget
Details:
Indicates that some progress has been made, but you do not know how much. Causes the progress bar to enter "activity mode", where a block bounces back and forth.

Each call to the gtk:progress-bar-pulse function causes the block to move by a little bit, the amount of movement per pulse is determined by the pulse-step property.
See also:
#2023-9-16

GtkLevelBar

GEnum gtk:level-bar-mode
Declaration:
(gobject:define-genum "GtkLevelBarMode" level-bar-mode
  (:export t
   :type-initializer "gtk_level_bar_mode_get_type")
  (:continuous 0)
  (:discrete 1))  
Values:
:continuous
The level bar has a continuous mode.
:discrete
The level bar has a discrete mode.
Details:
Describes how the gtk:level-bar widget contents should be rendered.
See also:
2024-10-31
Class gtk:level-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
inverted
The inverted property of type :boolean (Read / Write)
Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction.
Default value: false
max-value
The max-value property of type :double (Read / Write)
The property determines the maximum value of the interval that can be displayed by the level bar.
Allowed values: >= 0.0d0
Default value: 1.0d0
min-value
The min-value property of type :double (Read / Write)
The property determines the minimum value of the interval that can be displayed by the level bar.
Allowed values: >= 0.0d0
Default value: 0.0d0
mode
The mode property of type gtk:level-bar-mode (Read / Write)
The property determines the way a level bar interprets the value properties to draw the level fill area. Specifically, when the value is :continuous, the level bar will draw a single block representing the current value in that area. When the value is :discrete, the widget will draw a succession of separate blocks filling the draw area, with the number of blocks being equal to the units separating the integral roundings of the min-value and max-value values.
Default value: :continuous
value
The value property of type :double (Read / Write)
The property determines the currently filled value of the level bar.
Allowed values: >= 0.0d0
Default value: 0.0d0
Returned by:
Slot Access Functions:
Details:
The gtk:level-bar widget is a level bar widget that can be used as a level indicator. Typical use cases are displaying the strength of a password, or showing the charge level of a battery.

Figure: GtkLevelBar

Use the gtk:level-bar-value function to set the current value, and the gtk:level-bar-add-offset-value function to set the value offsets at which the level bar will be considered in a different state. GTK will add a few offsets by default on the level bar: "low", "high" and "full", with values 0.25, 0.75 and 1.0 respectively.

Note that it is your responsibility to update preexisting offsets when changing the minimum or maximum value. GTK will simply clamp them to the new range.

Adding a custom offset on the bar
The default interval of values is between zero and one, but it is possible to modify the interval using the gtk:level-bar-min-value and gtk:level-bar-max-value functions. The value will be always drawn in proportion to the admissible interval, that is, a value of 15 with a specified interval between 10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1. When the :discrete level bar mode is used, the level bar is rendered as a finite number of separated blocks instead of a single one. The number of blocks that will be rendered is equal to the number of units specified by the admissible interval.

For instance, to build a lever bar rendered with five blocks, it is sufficient to set the minimum value to 0 and the maximum value to 5 after changing the indicator mode to discrete.
GtkLevelBar as GtkBuildable:
The gtk:level-bar implementation of the gtk:buildable interface supports a custom <offsets> element, which can contain any number of <offset> elements, each of which must have name and value attributes.
CSS nodes:
levelbar[.discrete]
╰── trough
    ├── block.filled.level-name
    ┊
    ├── block.empty
    ┊    
The gtk:level-bar implementation has a main CSS node with name levelbar and one of the .discrete or .continuous style classes and a subnode with name trough. Below the trough node are a number of nodes with name block and .filled or .empty style class. In continuous mode, there is exactly one node of each, in discrete mode, the number of filled and unfilled nodes corresponds to blocks that are drawn. The block.filled nodes also get a .level-name style class corresponding to the level for the current value.

In horizontal orientation, the nodes are always arranged from left to right, regardless of text direction.
Examples:
Adding a custom offset on the bar.
(defun create-level-bar (orientation)
  (let* ((levelbar (make-instance 'gtk:level-bar
                                  :orientation orientation)))
    ;; This changes the value of the default low offset
    (gtk:level-bar-add-offset-value levelbar "low" 0.10d0)
    ;; This adds a new offset to the bar. The application will
    ;; be able to change its color CSS like this:
    ;;
    ;; levelbar block.my-offset {
    ;;   background-color: magenta;
    ;;   border-style: solid;
    ;;   border-color: black;
    ;;   border-style: 1px;
    ;; }
    (gtk:level-bar-add-offset-value levelbar "my-offset" 0.60d0)
    ;; Return the new level bar
    levelbar))    
Accessibility:
The gtk:level-bar implementation uses the :meter role of the gtk:accessible-role enumeration
Signal Details:
The "offset-changed" signal
lambda (levelbar name)    :detailed      
levelbar
The gtk:level-bar widget which received the signal.
name
The string with the name of the offset that changed value.
Emitted when an offset specified on the level bar changes value as an effect to the gtk:level-bar-add-offset-value function being called. The signal supports detailed connections. You can connect to the "changed::x" detailed signal in order to only receive callbacks when the value of "x" offset changes.
See also:
2024-10-31
Accessor gtk:level-bar-inverted (object)
Syntax:
(gtk:level-bar-inverted object) => inverted
(setf (gtk:level-bar-inverted object) inverted)
Arguments:
object -- a gtk:level-bar widget
inverted -- true to invert the level bar
Details:
Accessor of the inverted slot of the gtk:level-bar class. The gtk:level-bar-inverted function returns true if the level bar is inverted. The (setf gtk:level-bar-inverted) function sets the value of the property.
See also:
2024-4-25
Accessor gtk:level-bar-max-value (object)
Syntax:
(gtk:level-bar-max-value object) => value
(setf (gtk:level-bar-max-value object) value)
Arguments:
object -- a gtk:level-bar widget
value -- a double float with a positive value
Details:
Accessor of the max-value slot of the gtk:level-bar class. The gtk:level-bar-max-value function returns the value of the max-value property. The (setf gtk:level-bar-max-value) function sets the value.
See also:
2024-4-25
Accessor gtk:level-bar-min-value (object)
Syntax:
(gtk:level-bar-min-value object) => value
(setf (gtk:level-bar-min-value object) value)
Arguments:
object -- a gtk:level-bar widget
value -- a double float with a positive value
Details:
Accessor of the min-value slot of the gtk:level-bar class. The gtk:level-bar-min-value function returns the value of the min-value property. The (setf gtk:level-bar-min-value) function sets the value.
See also:
2024-4-25
Accessor gtk:level-bar-mode (object)
Syntax:
(gtk:level-bar-mode object) => mode
(setf (gtk:level-bar-mode object) mode)
Arguments:
object -- a gtk:level-bar widget
mode -- a value of the gtk:level-bar-mode enumeration
Details:
Accessor of the mode slot of the gtk:level-bar class. The gtk:level-bar-mode function returns the value of the mode property. The (setf gtk:level-bar-mode) function sets the value.
See also:
2024-4-25
Accessor gtk:level-bar-value (object)
Syntax:
(gtk:level-bar-value object) >= value
(setf (gtk:level-bar-value object) value)
Arguments:
object -- a gtk:level-bar widget
value -- a double float with a value in the interval between the min-value and max-value values
Details:
Accessor of the value slot of the gtk:level-bar class. The gtk:level-bar-value function gets the value of the level bar in the interval between the min-value and max-value values. The (setf gtk:level-bar-value) function sets the value.
See also:
2024-4-25
Function gtk:level-bar-new ()
Returns:
The new gtk:level-bar widget.
Details:
Creates a new level bar.
See also:
2024-10-31
Function gtk:level-bar-new-for-interval (min max)
Arguments:
min -- a double float with a positive value
max -- a double float with a positive value
Returns:
The new gtk:level-bar widget.
Details:
Utility constructor that creates a new level bar for the specified interval.
See also:
2024-10-31
Function gtk:level-bar-add-offset-value (levelbar name value)
Arguments:
levelbar -- a gtk:level-bar widget
name -- a string for the name of the new offset
value -- a double float for the new offset
Details:
Adds a new offset marker on the level bar at the position specified by value. When the level bar value is in the interval topped by value, or between the value and max-value values in case the offset is the last one on the bar, a style class named level-name will be applied when rendering the level bar fill. If another offset marker named name exists, its value will be replaced by value.
See also:
#2023-8-24
Function gtk:level-bar-remove-offset-value (levelbar name)
Arguments:
levelbar -- a gtk:level-bar widget
name -- a string with the name of an offset in the level bar
Details:
Removes an offset marker previously added with the gtk:level-bar-add-offset-value function.
See also:
#2023-8-24
Function gtk:level-bar-offset-value (levelbar name)
Arguments:
levelbar -- a gtk:level-bar widget
name -- a string for the name of an offset in the level bar
Returns:
The double float which specified the offset marker.
Details:
Fetches the value specified for the offset marker name in the level bar, returning nil in case an offset named name was not found.
See also:
#2023-8-24

GtkCalendar

Class gtk:calendar
Superclasses:
Documented Subclasses:
None
Direct Slots:
day
The day property of type :int (Read / Write)
The selected day as a number between 1 and 31, or 0 to unselect the currently selected day. This property gets initially set to the current day.
Allowed values: [0, 31]
Default value: 0
month
The month property of type :int (Read / Write)
The selected month as a number between 0 and 11. This property gets initially set to the current month.
Allowed values: [0, 11]
Default value: 0
show-day-names
The show-day-names property of type :boolean (Read / Write)
Determines whether day names are displayed.
Default value: true
show-heading
The show-heading property of type :boolean (Read / Write)
Determines whether a heading is displayed.
Default value: true
show-week-numbers
The show-week-numbers property of type :boolean (Read / Write)
Determines whether week numbers are displayed.
Default value: false
year
The year property of type :int (Read / Write)
The selected year. This property gets initially set to the current year.
Allowed values: [0, 4194303]
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:calendar widget displays a Gregorian calendar, one month at a time. It can be created with the gtk:calendar-new function.

Figure: GtkCalendar

The date that is currently displayed can be altered with the gtk:calendar-select-day function. The selected date can be retrieved from a gtk:calendar widget using the gtk:calendar-date function.

To place a visual marker on a particular day, use the gtk:calendar-mark-day function and to remove the marker, the gtk:calendar-unmark-day function. Alternative, all marks can be cleared with the gtk:calendar-clear-marks function.

Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect.
CSS nodes:
calendar.view
├── header
│   ├── button
│   ├── stack.month
│   ├── button
│   ├── button
│   ├── label.year
│   ╰── button
╰── grid
    ╰── label[.day-name][.week-number][.day-number][.other-month][.today]    
The gtk:calendar implementation has a main node with name calendar. It contains a subnode called header containing the widgets for switching between years and months. The grid subnode contains all day labels, including week numbers on the left. marked with the .week-number style class, and day names on top, marked with the .day-name style class. Day labels that belong to the previous or next month get the .other-month style class. The label of the current day get the .today style class. Marked day labels get the :selected state assigned.
Signal Details:
The "day-selected" signal
lambda (calendar)    :run-first      
calendar
The gtk:calendar widget which received the signal.
The signal is emitted when the user selects a day.
The "next-month" signal
lambda (calendar)    :run-first      
calendar
The gtk:calendar widget which received the signal.
The signal is emitted when the user switched to the next month.
The "next-year" signal
lambda (calendar)    :run-first      
calendar
The gtk:calendar widget which received the signal.
The signal is emitted when user switched to the next year.
The "prev-month" signal
lambda (calendar)    :run-first      
calendar
The gtk:calendar widget which received the signal.
The signal is emitted when the user switched to the previous month.
The "prev-year" signal
lambda (calendar)    :run-first      
calendar
The gtk:calendar widget which received the signal.
The signal is emitted when user switched to the previous year.
2024-10-31
Accessor gtk:calendar-day (object)
Syntax:
(gtk:calender-day object) => day
(setf (gtk:calendar-day object) day)
Arguments:
object -- a gtk:calendar widget
day -- an integer with the selected day
Details:
Accessor of the day slot of the gtk:calendar class. The selected day as a number between 1 and 31, or 0 to unselect the currently selected day. This property gets initially set to the current day.
See also:
2024-7-5
Accessor gtk:calendar-month (object)
Syntax:
(gtk:calendar-month object) => month
(setf (gtk:calendar-month object) month)
Arguments:
object -- a gtk:calendar widget
month -- an integer with the selected month
Details:
Accessor of the month slot of the gtk:calendar class.
See also:
2024-7-5
Accessor gtk:calendar-show-day-names (object)
Syntax:
(gtk:calendar-show-day-names object) => setting
(setf (gtk:calendar-show-day-names object) setting)
Arguments:
object -- a gtk:calendar widget
setting -- a boolean whether day names are displayed
Details:
Accessor of the show-day-names slot of the gtk:calendar class. Determines whether day names are displayed.
See also:
2024-7-5
Accessor gtk:calendar-show-heading (object)
Syntax:
(gtk:calendar-show-heading object) => setting
(setf (gtk:calendar-show-heading object) setting)
Arguments:
object -- a gtk:calendar widget
setting -- a boolean whether a heading is displayed
Details:
Accessor of the show-heading slot of the gtk:calendar class. Determines whether a heading is displayed.
See also:
2024-7-5
Accessor gtk:calendar-show-week-numbers (object)
Syntax:
(gtk:calendar-show-week-numbers object) => setting
(setf (gtk:calendar-show-week-numbers object) setting)
Arguments:
object -- a gtk:calendar widget
setting -- a boolean whether week numbers are displayed
Details:
Accessor of the show-week-numbers slot of the gtk:calendar class. Determines whether week numbers are displayed.
See also:
2024-7-5
Accessor gtk:calendar-year (object)
Syntax:
(gtk:calendar-year object) => year
(setf (gtk:calendar-year object) year)
Arguments:
object -- a gtk:calendar widget
year -- an integer with the selected year
Details:
Accessor of the year slot of the gtk:calendar class. The selected year. This property gets initially set to the current year.
See also:
2024-7-5
Function gtk:calendar-new ()
Returns:
The new gtk:calendar widget.
Details:
Creates a new calendar, with the current date being selected.
See also:
2024-10-31
Function gtk:calendar-select-day (calendar year month day)
Arguments:
calendar -- a gtk:calendar widget
year -- an integer with the year
month -- an integer with the month
day -- an integer with the day between 1 and 31
Details:
Will switch to the year and month of the date and select its day.
See also:
2024-7-5
Function gtk:calendar-mark-day (calendar day)
Arguments:
calendar -- a gtk:calendar widget
day -- an unsigned integer with the day to mark between 1 and 31
Details:
Places a visual marker on a particular day.
See also:
2024-7-5
Function gtk:calendar-unmark-day (calendar day)
Arguments:
calendar -- a gtk:calendar widget
day -- an unsigned integer with the day to unmark between 1 and 31
Details:
Removes the visual marker from a particular day.
See also:
2024-7-5
Function gtk:calendar-day-is-marked (calendar day)
Arguments:
calendar -- a gtk:calendar widget
day -- an unsigned integer with the day between 1 and 31
Returns:
The boolean whether the day is marked.
Details:
Returns if the day of the calendar is already marked.
See also:
2024-7-5
Function gtk:calendar-clear-marks (calendar)
Arguments:
calendar -- a gtk:calendar widget
Details:
Remove all visual markers.
See also:
2024-7-5
Function gtk:calendar-date (calendar)
Arguments:
calendar -- a gtk:calendar widget
Returns:
year -- an integer with the year as a decimal number, for example 2024
month -- an integer with the month number, between 0 and 11
day -- an integer with the day number, between 1 and 31
Details:
Obtains the selected date from the calendar.
See also:
2024-7-5

Media Support

GtkGraphicsOffload

GEnum gtk:graphics-offload-enabled
Declaration:
(gobject:define-genum "GtkGraphicsOffloadEnabled" graphics-offload-enabled
  (:export t
   :type-initializer "gtk_graphics_offload_enabled_get_type")
  (:enabled 0)
  (:disabled 1))  
Values:
:enabled
Graphics offloading is enabled.
:disabled
Graphics offloading is disabled.
Details:
Represents the state of graphics offloading.

Since 4.14
See also:
2024-11-9
Class gtk:graphics-offload
Superclasses:
Documented Subclasses:
None
Direct Slots:
black-background
The black-background property of type :boolean (Read / Write)
Whether to draw a black background. Since 4.16
Default value: false
child
The child property of type gtk:widget (Read / Write)
The child widget.
enabled
The enabled property of type gtk:graphics-offload-enabled (Read / Write)
Whether graphics offload is enabled.
Default value: :enabled
Returned by:
Slot Access Functions:
Details:
The gtk:graphics-offload widget is a widget that allows to bypass GSK rendering for its child by passing the content directly to the compositor. Graphics offload is an optimization to reduce overhead and battery use that is most useful for video content. It only works on some platforms and in certain situations. GTK will automatically fall back to normal rendering if it does not.

Graphics offload is most efficient if there are no controls drawn on top of the video content. You should consider using graphics offload for your main widget if it shows frequently changing content, such as a video, or a VM display, and you provide the content in the form of dma-buf textures, see the gdk:dmabuf-texture-builder documentation, in particular if it may be fullscreen.

Numerous factors can prohibit graphics offload:
  • Unsupported platforms. Currently, graphics offload only works on Linux with Wayland.
  • Clipping, such as rounded corners that cause the video content to not be rectangular.
  • Unsupported dma-buf formats, see the gdk:display-dmabuf-formats function.
  • Translucent video content, content with an alpha channel, even if it is not used.
  • Transforms that are more complex than translations and scales.
  • Filters such as opacity, grayscale or similar.
The GTK inspector provides a visual debugging tool for graphics offload.

Since 4.14
See also:
2024-11-9
Accessor gtk:graphics-offload-black-background (object)
Syntax:
(gtk:graphics-offload-black-background object) => setting
(setf (gtk:graphics-offload-black-background object) setting)
Arguments:
object -- a gtk:graphics-offload widget
setting -- a boolean whether to draw a black background behind the content
Details:
Accessor of the black-background slot of the gtk:graphics-offload class. The gtk:graphics-offload-black-background function returns whether the widget draws a black background. The (setf gtk:graphics-offload-black-background) function sets whether object will draw a black background.

A main use case for this is letterboxing where black bars are visible next to the content if the aspect ratio of the content does not match the dimensions of the monitor. Using this property for letterboxing instead of CSS allows compositors to show content with maximum efficiency, using direct scanout to avoid extra copies in the compositor.

On Wayland, this is implemented using the single-pixel buffer protocol.

Since 4.16
See also:
2024-11-9
Accessor gtk:graphics-offload-child (object)
Syntax:
(gtk:graphics-offload-child object) => child
(setf (gtk:graphics-offload-child object) child)
Arguments:
object -- a gtk:graphics-offload widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:graphics-offload class. The gtk:graphics-offload-child function gets the child widget. The (setf gtk:graphics-offload-child) function sets the child widget.

Since 4.14
See also:
2024-11-9
Accessor gtk:graphics-offload-enabled (object)
Syntax:
(gtk:graphics-offload-enabled object) => setting
(setf (gtk:graphics-offload-enabled object) setting)
Arguments:
object -- a gtk:graphics-offload widget
setting -- a gtk:graphics-offload-enabled value
Details:
Accessor of the enabled slot of the gtk:graphics-offload class. The gtk:graphics-offload-enabled function returns whether offload is enabled. The (setf gtk:graphics-offload-enabled) function sets whether the gtk:graphics-offload widget will attempt to offload the content of its child widget.

Since 4.14
See also:
2024-11-9
Function gtk:graphics-offload-new (&optional child)
Arguments:
child -- an optional gtk:widget child widget
Returns:
The new gtk:graphics-offload widget.
Details:
Creates a new gtk:graphics-offload widget.

Since 4.14
See also:
2024-11-9

GtkVideo

Class gtk:video
Superclasses:
Documented Subclasses:
None
Direct Slots:
autoplay
The autoplay property of type :boolean (Read / Write)
Whether the video should automatically begin playing.
Default value: false
file
The file property of type g:file (Read / Write)
The file played back by the video if the video is playing a file.
graphics-offload
The graphics-offload property of type gtk:graphics-offload-enabled (Read / Write)
Whether to enable graphics offload. Since 4.14
Default value: :disabled
loop
The loop property of type :boolean (Read / Write)
Whether new media files should be set to loop.
Default value: false
media-stream
The media-stream property of type gtk:media-stream (Read / Write)
The media stream played back.
Returned by:
Slot Access Functions:
Details:
The gtk:video widget is a widget to show a gtk:media-stream object with media controls.

Figure: GtkVideo

The controls are available separately as the gtk:media-controls widget. If you just want to display a video without controls, you can treat it like any other paintable and, for example, put it into a gtk:picture widget.

The gtk:video widget aims to cover use cases such as previews, embedded animations, and so on. It supports autoplay, looping, and simple media controls. It does not have support for video overlays, multichannel audio, device selection, or input. If you are writing a full-fledged video player, you may want to use the gdk:paintable API and a media framework such as GStreamer directly.
See also:
2024-10-31
Accessor gtk:video-autoplay (object)
Syntax:
(gtk:video-autoplay object) => autoplay
(setf (gtk:video-autoplay object) autoplay)
Arguments:
object -- a gtk:video widget
autoplay -- a boolean whether media streams should autoplay
Details:
Accessor of the autoplay slot of the gtk:video class. The gtk:video-autoplay function returns true if videos have been set to loop via the gtk:video-loop function. The (setf gtk:video-autoplay) function sets whether self automatically starts playback when it becomes visible or when a new file gets loaded.
See also:
2024-10-31
Accessor gtk:video-file (object)
Syntax:
(gtk:video-file object) => file
(setf (gtk:video-file object) file)
Arguments:
object -- a gtk:video widget
file -- a g:file object to play
Details:
Accessor of the file slot of the gtk:video class. The gtk:video-file function gets the file played back by object or nil if not playing back a file. The (setf gtk:video-file) function makes object playback the given file.
See also:
2024-10-31
Accessor gtk:video-graphics-offload (object)
Syntax:
(gtk:video-graphics-offload object) => setting
(setf (gtk:video-graphics-offload object) setting)
Arguments:
object -- a gtk:video widget
setting -- a gtk:graphics-offload-enabled value
Details:
Accessor of the graphics-offload slot of the gtk:video class. The gtk:video-graphics-offload function returns whether graphics offload is enabled. The (setf gtk:video-graphics-offload) function sets whether to enable graphics offload. See the gtk:graphics-offload-enabled documentation for more information on graphics offload.

Since 4.14
See also:
2024-10-31
Accessor gtk:video-loop (object)
Syntax:
(gtk:video-loop object) => loop
(setf (gtk:video-loop object) loop)
Arguments:
object -- a gtk:video widget
loop -- a boolean whether media streams should loop
Details:
Accessor of the loop slot of the gtk:video class. The gtk:video-loop function returns true if videos have been set to loop. The (setf gtk:video-loop) function sets whether new files loaded by object should be set to loop.
See also:
2024-10-31
Accessor gtk:video-media-stream (object)
Syntax:
(gtk:video-media-stream object) => stream
(setf (gtk:video-media-stream object) stream)
Arguments:
object -- a gtk:video widget
stream -- a gtk:media-stream object to play or nil to unset
Details:
Accessor of the media-stream slot of the gtk:video class. The gtk:video-media-stream function gets the media stream managed by object or nil if none. The (setf gtk:video-media-stream) function sets the media stream to be played back. The object argument will take full control of managing the media stream. If you want to manage a media stream yourself, consider using a gtk:picture widget for display.

If you want to display a file, consider using the gtk:video-file function instead.
See also:
2024-10-31
Function gtk:video-new ()
Returns:
The new gtk:video widget.
Details:
Creates a new empty gtk:video widget.
See also:
2024-10-31
Function gtk:video-new-for-media-stream (stream)
Arguments:
stream -- a gtk:media-stream object
Returns:
The new gtk:video widget.
Details:
Creates a new gtk:video widget to playback the given media stream.
See also:
2024-10-31
Function gtk:video-new-for-file (file)
Arguments:
file -- a g:file object
Returns:
The new gtk:video widget.
Details:
Creates a new gtk:video widget to playback the given file.
See also:
2024-10-31
Function gtk:video-new-for-filename (path)
Arguments:
path -- a pathname or namestring with the file to playback
Returns:
The new gtk:video widget.
Details:
Creates a new gtk:video widget to playback the given file. This is a utility function that calls the gtk:video-new-for-file function.
See also:
2024-10-31
Function gtk:video-new-for-resource (path)
Arguments:
path -- a string with the resource path to playback
Returns:
The new gtk:video widget.
Details:
Creates a new gtk:video widget to playback the given resource. This is a utility function that calls the gtk:video-new-for-file function.
See also:
2024-10-31
Function gtk:video-set-filename (video path)
Arguments:
video -- a gtk:video widget
path -- a pathname or namestring with the file to playback
Details:
Makes object playback the given file. This is a utility function that calls the gtk:video-file function.
See also:
2024-10-31
Function gtk:video-set-resource (video path)
Arguments:
video -- a gtk:video widget
path -- a string with the resource to playback
Details:
Makes object playback the given resource. This is a utility function that calls the gtk:video-file function.
See also:
2024-10-31

GtkMediaControls

Class gtk:media-controls
Superclasses:
Documented Subclasses:
None
Direct Slots:
media-stream
The media-stream property of type gtk:media-stream (Read / Write)
The media stream managed by the media controls.
Details:
The gtk:media-controls widget is a widget to show controls for a gtk:media-stream object and giving users a way to use it.

Figure: GtkMediaControls

Usually, the gtk:media-controls widget is used as part of the gtk:video widget.
See also:
2024-10-31
Accessor gtk:media-controls-media-stream (object)
Syntax:
(gtk:media-controls-media-stream object) => stream
(setf (gtk:media-controls-media-stream object) stream)
Arguments:
object -- a gtk:media-controls widget
stream -- a gtk:media-stream object, or nil
Details:
Accessor of the media-stream slot of the gtk:media-controls class. The gtk:media-controls-media-stream function gets the media stream managed by the media controls or nil if none. The (setf gtk:media-controls-media-stream) function sets the media stream.
See also:
2024-10-31
Function gtk:media-controls-new (stream)
Arguments:
stream -- a gtk:media-stream object
Returns:
The new gtk:media-controls widget.
Details:
Creates the new media controls managing the media stream passed to it.
See also:
2024-10-31

GtkMediaStream

Class gtk:media-stream
Superclasses:
gdk:paintable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
duration
The duration property of type :int64 (Read)
The stream's duration in microseconds or 0 if unknown.
Allowed values: >= 0
Default value: 0
ended
The ended property of type :boolean (Read)
Set when playback has finished.
Default value: false
error
The error property of type GError (Read)
Nil for a properly working stream or the GError that the stream is in.
has-audio
The has-audio property of type :boolean (Read)
Whether the stream contains audio.
Default value: false
has-video
The has-video property of type :boolean (Read)
Whether the stream contains video.
Default value: false
loop
The loop property of type :boolean (Read / Write)
Try to restart the media from the beginning once it ended.
Default value: false
muted
The muted property of type :boolean (Read / Write)
Whether the audio stream should be muted.
Default value: false
playing
The playing property of type :boolean (Read / Write)
Whether the audio stream should be muted.
Default value: false
prepared
The prepared property of type :boolean (Read / Write)
Whether the stream has finished initializing and existence of audio and video is known.
Default value: false
seekable
The seekable property of type :boolean (Read)
Set unless the stream is known to not support seeking.
Default value: true
seeking
The seeking property of type :boolean (Read)
Set while a seek is in progress.
Default value: false
timestamp
The timestamp property of type :int64 (Read)
The current presentation timestamp in microseconds.
Allowed values: >= 0
Default value: 0
volume
The volume property of type :double (Read / Write)
Volume of the audio stream.
Allowed values: [0,1]
Default value: 1
Slot Access Functions:
Details:
The gtk:media-stream object is the integration point for media playback inside GTK. GTK provides an implementation of the gtk:media-stream interface that is called the gtk:media-file object.

Apart from application-facing API for stream playback, the gtk:media-stream object has a number of APIs that are only useful for implementations and should not be used in applications: gtk:media-stream-prepared, gtk:media-stream-unprepared, gtk.media-stream-update, gtk:media-stream-ended, gtk:media-stream-seek-success, gtk:media-stream-seek-failed, gtk:media-stream-gerror, gtk:media-stream-error, gtk:media-stream-error-valist functions.
See also:
#2023-5-2
Accessor gtk:media-stream-duration (object)
Syntax:
(gtk:media-stream-duration object) => duration
Arguments:
object -- a gtk:media-stream object
duration -- an integer with the duration of the stream
Details:
Accessor of the duration slot of the gtk:media-stream class. The gtk:media-stream-duration function gets the duration of the stream. If the duration is not known, 0 will be returned.
See also:
#2023-5-2
Accessor gtk:media-stream-ended (object)
Syntax:
(gtk:media-stream-ended object) => ended
Arguments:
object -- a gtk:media-stream object
ended -- a boolean whether the playback is finished
Details:
Accessor of the ended slot of the gtk:media-stream class. The gtk:media-stream-ended function returns whether the streams playback is finished.
See also:
#2023-5-2
Accessor gtk:media-stream-error (object)
Syntax:
(gtk:media-stream-error object) => error
Arguments:
object -- a gtk:media-stream object
error -- nil if not in an error state or the GError of the stream
Details:
Accessor of the error slot of the gtk:media-stream class. If the stream is in an error state, the gtk:media-stream-error function returns the GError explaining that state. Any type of error can be reported here depending on the implementation of the media stream.

A media stream in an error cannot be operated on, calls like the gtk:media-stream-play or gtk:media-stream-seek functions will not have any effect.

The gtk:media-stream object itself does not provide a way to unset an error, but implementations may provide options. For example, a gtk:media-file object will unset errors when a new source is set, for example, with the gtk:media-file-set-file function.
See also:
#2023-5-2
Accessor gtk:media-stream-has-audio (object)
Syntax:
(gtk:media-stream-has-audio object) => setting
Arguments:
object -- a gtk:media-stream object
setting -- true if the stream has audio
Details:
Accessor of the has-audio slot of the gtk:media-stream class. The gtk:media-stream-has-audio function returns whether the stream has audio.
See also:
#2023-5-2
Accessor gtk:media-stream-has-video (object)
Syntax:
(gtk:media-stream-has-video object) => setting
Arguments:
object -- a gtk:media-stream object
setting -- true if the stream has video
Details:
Accessor of the has-video slot of the gtk:media-stream class. The gtk:media-stream-has-video function returns whether the stream has video.
See also:
#2023-5-2
Accessor gtk:media-stream-loop (object)
Syntax:
(gtk:media-stream-loop object) => setting
(setf (gtk:media-stream-loop object) setting)
Arguments:
object -- a gtk:media-stream object
setting -- true if the stream should loop
Details:
Accessor of the loop slot of the gtk:media-stream class. The gtk:media-stream-loop function returns whether the stream is set to loop. The (setf gtk:media-stream-loop) function sets whether the stream should loop, that is, restart playback from the beginning instead of stopping at the end.

Not all streams may support looping, in particular non-seekable streams. Those streams will ignore the loop setting and just end.
See also:
#2023-5-2
Accessor gtk:media-stream-muted (object)
Syntax:
(gtk:media-stream-muted object) => setting
(setf (gtk:media-stream-muted object) setting)
Arguments:
object -- a gtk:media-stream object
setting -- true if the stream should be muted
Details:
Accessor of the muted slot of the gtk:media-stream class. The gtk:media-stream-muted function returns whether the audio for the stream is muted. The (setf gtk:media-stream-muted) function sets whether the audio stream should be muted. Muting a stream will cause no audio to be played, but it does not modify the volume. This means that muting and then unmuting the stream will restore the volume settings.

If the stream has no audio, calling this function will still work but it will not have an audible effect.
See also:
#2023-5-2
Accessor gtk:media-stream-playing (object)
Syntax:
(gtk:media-stream-playing object) => setting
(setf (gtk:media-stream-playing object) setting)
Arguments:
object -- a gtk:media-stream object
setting -- a boolean whether to start or pause playback
Details:
Accessor of the playing slot of the gtk:media-stream class. The gtk:media-stream-playing function returns whether the stream is currently playing. The (setf gtk:media-stream-playing) function starts or pauses playback of the stream.
See also:
#2023-5-2
Accessor gtk:media-stream-prepared (object)
Syntax:
(gtk:media-stream-prepared object) => setting
(setf (gtk:media-stream-prepared object) setting)
Arguments:
object -- a gtk:media-stream object
setting -- a boolean whether the stream has finished initializing and existence of audio and video is known
Details:
Accessor of the prepared slot of the gtk:media-stream class.
See also:
#2023-5-2
Accessor gtk:media-stream-seekable (object)
Syntax:
(gtk:media-stream-seekable object) => setting
Arguments:
object -- a gtk:media-stream object
setting -- a boolean whether the stream is known to support seeking
Details:
Accessor of the seekable slot of the gtk:media-stream class.
See also:
#2023-5-2
Accessor gtk:media-stream-seeking (object)
Syntax:
(gtk:media-stream-seeking object) => setting
Arguments:
object -- a gtk:media-stream object
setting -- a boolean whether a seek is in progress
Details:
Accessor of the seeking slot of the gtk:media-stream class.
See also:
#2023-5-2
Accessor gtk:media-stream-timestamp (object)
Syntax:
(gtk:media-stream-timestamp object) => timestamp
Arguments:
object -- a gtk:media-stream object
timestamp -- an integer with the timestamp in microseconds
Details:
Accessor of the timestamp slot of the gtk:media-stream class. The gtk:media-stream-timestamp function returns the current presentation timestamp in microseconds.
See also:
#2023-5-2
Accessor gtk:media-stream-volume (object)
Syntax:
(gtk:media-stream-volume object) => volume
(setf (gtk:media-stream-playing object) volume)
Arguments:
object -- a gtk:media-stream object
volume -- a double float with the volume of the stream from 0.0 to 1.0
Details:
Accessor of the volume slot of the gtk:media-stream class. The gtk:media-stream-volume function returns the volume of the audio for the stream. The (setf gtk:media-stream-volume) function sets the volume of the audio stream. This function call will work even if the stream is muted.

The given volume should range from 0.0 for silence to 1.0 for as loud as possible. Values outside of this range will be clamped to the nearest value.

If the stream has no audio or is muted, calling this function will still work but it will not have an immediate audible effect. When the stream is unmuted, the new volume setting will take effect.
See also:
#2023-5-2
Function gtk:media-stream-is-prepared (stream)
Arguments:
stream -- a gtk:media-stream object
Returns:
True if the stream is prepared.
Details:
Returns whether the stream has finished initializing and existence of audio and video is known.
See also:
#2023-5-3
Function gtk:media-stream-play (stream)
Arguments:
stream -- a gtk:media-stream object
Details:
Starts playing the stream. If the stream is in error or already playing, do nothing.
See also:
#2023-5-3
Function gtk:media-stream-pause (stream)
Arguments:
stream -- a gtk:media-stream object
Details:
Pauses playback of the stream. If the stream is not playing, do nothing.
See also:
#2023-5-3
Function gtk:media-stream-is-seekable (stream)
Arguments:
stream -- a gtk:media-stream object
Returns:
True if the stream may support seeking.
Details:
Checks if a stream may be seekable. This is meant to be a hint. Streams may not allow seeking even if this function returns true . However, if this function returns false, streams are guaranteed to not be seekable and user interfaces may hide controls that allow seeking.

It is allowed to call the gtk:media-stream-seek function on a non seekable stream, though it will not do anything.
See also:
#2023-5-3
Function gtk:media-stream-is-seeking (stream)
Arguments:
stream -- a gtk:media-stream object
Returns:
True if a seek is ongoing.
Details:
Checks if there is currently a seek operation going on.
See also:
#2023-5-3
Function gtk:media-stream-seek (stream timestamp)
Arguments:
stream -- a gtk:media-stream object
timestamp -- an integer with the timestamp to seek to
Details:
Start a seek operation on stream to timestamp. If timestamp is out of range, it will be clamped.

Seek operations may not finish instantly. While a seek operation is in process, the seeking property will be set.

When calling gtk:media-stream-seek function during an ongoing seek operation, the new seek will override any pending seek.
See also:
#2023-5-3
Function gtk:media-stream-realize (stream surface)
Arguments:
stream -- a gtk:media-stream object
surface -- a gdk:surface object
Details:
Called by users to attach the media stream to a gdk:surface object they manage. The stream can then access the resources of surface for its rendering purposes. In particular, media streams might want to create gdk:gl-context objects or sync to the gdk:frame-clock object.

Whoever calls this function is responsible for calling the gtk:media-stream-unrealize function before either the stream or surface get destroyed.

Multiple calls to this function may happen from different users of the video, even with the same surface . Each of these calls must be followed by its own call to the gtk:media-stream-unrealize function.

It is not required to call this function to make a media stream work.
See also:
#2023-5-3
Function gtk:media-stream-unrealize (stream surface)
Arguments:
stream -- a gtk:media-stream object previously realized
surface -- a gdk:surface object the stream was realized with
Details:
Undoes a previous call to the gtk:media-stream-realize function and causes the stream to release all resources it had allocated from surface.
See also:
#2023-5-3
Function gtk:media-stream-update (stream timestamp)
Arguments:
stream -- a gtk:media-stream object
timestamp -- an integer with the new timestamp
Details:
Media stream implementations should regularly call this function to update the timestamp reported by the stream. It is up to implementations to call this at the frequency they deem appropriate.
See also:
#2023-5-3
Function gtk:media-stream-seek-success (stream)
Arguments:
stream -- a gtk:media-stream object
Details:
Ends a seek operation started via the gtk:media-stream-seek function successfully. This function will unset the ended property if it was set.

See the gtk:media-stream-seek-failed function for the other way of ending a seek.
See also:
#2023-5-3
Function gtk:media-stream-seek-failed (stream)
Arguments:
stream -- a gtk:media-stream object
Details:
Ends a seek operation started via the gtk:media-stream-seek function as a failure. This will not cause an error on the stream and will assume that playback continues as if no seek had happened.

See the gtk:media-stream-seek-success function for the other way of ending a seek.
See also:
#2023-5-3

GtkMediaFile

Class gtk:media-file
Superclasses:
gtk:media-stream, gdk:paintable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
file
The file property of type g:file (Read / Write)
The file being played back or nil if not playing a file.
Returned by:
Slot Access Functions:
Details:
The gtk:media-file class is the implementation for media file usage with the gtk:media-stream class. This provides a simple way to play back video files with GTK.

GTK provides a GIO extension point for gtk:media-file implementations to allow for external implementations using various media frameworks. GTK itself includes implementations using GStreamer and ffmpeg.
See also:
2024-10-31
Accessor gtk:media-file-file (object)
Syntax:
(gtk:media-file-file object) => file
(setf (gtk:media-file-file object) file)
Arguments:
object -- a gtk:media-file object
file -- a g:file object with the file to play
Details:
Accessor of the file slot of the gtk:media-file class. The gtk:media-file-file function returns the file that object is currently playing from. When object is not playing or not playing from a file, nil is returned.

The (setf gtk:media-file-file) function sets the file. If any file is still playing, stop playing it. Then start playing the given file.
See also:
2024-10-31
Function gtk:media-file-new ()
Returns:
The new gtk:media-file object.
Details:
Creates a new empty media file.
See also:
2024-10-31
Function gtk:media-file-new-for-filename (path)
Arguments:
filename -- a pathname or namestring with the file to open
Returns:
The new gtk:media-file object playing filename.
Details:
Creates a new media file. This is a utility function that converts the given filename to a g:file object and calls the gtk:media-file-new-for-file function.
See also:
2024-10-31
Function gtk:media-file-new-for-resource (path)
Arguments:
path -- a string with the resource path to open
Returns:
The new gtk:media-file object playing path.
Details:
Creates a new media file. This is a utility function that converts the given resource to a g:file object and calls the gtk:media-file-new-for-file function.
See also:
2024-10-31
Function gtk:media-file-new-for-file (file)
Arguments:
file -- a g:file object with the file to play
Returns:
The new gtk:media-file object playing file.
Details:
Creates a new media file.
See also:
2024-10-31
Function gtk:media-file-clear (mediafile)
Arguments:
mediafile -- a gtk:media-file object
Details:
Resets the media file to be empty.
See also:
2024-10-31
Function gtk:media-file-set-filename (mediafile path)
Arguments:
mediafile -- a gtk:media-file object
path -- a pathname or namestring with the name of file to play
Details:
This is a utility function that converts the given filename to a g:file object and calls the gtk:media-file-file function.
See also:
2024-10-31
Function gtk:media-file-set-resource (mediafile path)
Arguments:
mediafile -- a gtk:media-file object
path -- a string with the path to the resource to playback
Details:
This is a utility function that converts the given path to a g:file object and calls the gtk:media-file-file function.
See also:
2024-10-31

Buttons and Toggles

GtkButton

Class gtk:button
Superclasses:
Documented Subclasses:
Direct Slots:
can-shrink
The can-shrink property of type :boolean (Read / Write)
Whether the size of the button can be made smaller than the natural size of its contents. For text buttons, setting this property will allow ellipsizing the label. If the contents of a button are an icon or a custom widget, setting this property has no effect. Since 4.12
Default value: false
child
The child property of type gtk:widget (Read / Write)
The child widget.
Default value: nil
has-frame
The has-frame property of type :boolean (Read / Write)
Whether the button has a frame.
Default value: true
icon-name
The icon-name property of type :string (Read / Write)
The name of the icon used to automatically populate the button.
Default value: nil
label
The label property of type :string (Read / Write)
The text of the label inside the button, if the button contains a label.
Default value: nil
use-underline
The use-underline property of type :boolean (Read / Write)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:button widget is generally used to trigger a callback function that is called when the button is pressed.

Figure: GtkButton

The gtk:button widget can hold any valid child widget. That is, it can hold almost any other standard gtk:widget object. The most commonly used child is the gtk:label widget.
CSS nodes:
The gtk:button implementation has a single CSS node with name button. The node will get the .image-button or .text-button style classes, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button from the keyboard, it will temporarily acquires the .keyboard-activating style class.

Other style classes that are commonly used with the gtk:button implementation include the .suggested-action and .destructive-action style classes. In special cases, buttons can be made round by adding the .circular style class.

Button-like widgets like the gtk:toggle-button, gtk:menu-button, gtk:volume-button, gtk:lock-button, gtk:color-button or gtk:font-button widgets use style classes such as the .toggle, .popup, .scale, .lock, .color style classes on the button node to differentiate themselves from a plain gtk:button widget.
Signal Details:
The "activate" signal
lambda (button)    :action      
button
The gtk:button widget which received the signal.
This signal is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the "clicked" signal.
The "clicked" signal
lambda (button)    :action      
button
The gtk:button widget which received the signal.
Emitted when the button has been activated (pressed and released).
See also:
2024-10-31
Accessor gtk:button-child (object)
Syntax:
(gtk:button-child object) => child
(setf (gtk:button-child object) child)
Arguments:
object -- a gtk:button widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:button class. The gtk:button-child function gets the child widget of the button. The (setf gtk:button-child) function sets the child widget.

Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for the button. Most likely, you will either set the accessibility label or description for the button explicitly, or you will set a labelled-by or described-by relations from the child widget to the button.
Examples:
Get the text of the label from the button:
(defvar button (gtk:button-new-with-label "Save"))
=> BUTTON
(gtk:label-label (gtk:button-child button))
=> "Save"    
Create a button with an image and a label:
(defvar button (gtk:button-new))
=> BUTTON
(defvar box (gtk:box-new :horizontal 9))
=> BOX
(gtk:box-append box (make-instance 'gtk:image :icon-name "edit-clear"))
(gtk:box-append box (make-instance 'gtk:label :label "Edit Clear"))
(setf (gtk:button-child button) box)
=> #<GTK:BOX {1003471C73}>    
See also:
2024-5-4
Accessor gtk:button-has-frame (object)
Syntax:
(gtk:button-has-frame object) => setting
(setf (gtk:button-has-frame object) setting)
Arguments:
object -- a gtk:button widget
setting -- a boolean whether the button has a frame
Details:
Accessor of the has-frame slot of the gtk:button class. The gtk:button-has-frame function returns whether the button has a frame. The (setf gtk:button-has-frame) function sets the style of the button. Buttons can have a flat appearance or a frame drawn around them.
See also:
2024-5-4
Accessor gtk:button-icon-name (object)
Syntax:
(gtk:button-icon-name object) => name
(setf (gtk:button-icon-name object) name)
Arguments:
object -- a gtk:button widget
name -- a string with an icon name, or nil
Details:
Accessor of the icon-name slot of the gtk:button class. The gtk:button-icon-name function returns the icon name of the button. If the icon name has not been set the return value will be nil. This will be the case if you create an empty button with the gtk:button-new function to use as a container. The (setf gtk:button-icon-name) function adds a gtk:image widget with the given icon name as a child widget. If the button already contains a child widget, that child widget will be removed and replaced with the image.
See also:
2024-5-14
Accessor gtk:button-label (object)
Syntax:
(gtk:button-label object) => label
(setf (gtk:button-label object) label)
Arguments:
object -- a gtk:button widget
label -- a string with the text of the label
Details:
Accessor of the label slot of the gtk:button class. The gtk:button-label function fetches the text from the label of the button. The (setf gtk:button-label) function sets the text. If the label text has not been set the return value will be nil. This will be the case if you create an empty button with the gtk:button-new function to use as a container.
See also:
2023-9-2
Accessor gtk:button-use-underline (object)
Syntax:
(gtk:button-use-underline object) => setting
(setf (gtk:button-use-underline object) setting)
Arguments:
object -- a gtk:button widget
setting -- true if underlines in the text indicate mnemonics
Details:
Accessor of the use-underline slot of the gtk:button class. The gtk:button-use-underline function gets whether underlines are interpreted as mnemonics. The (setf gtk:button-use-underline) function sets whether to use underlines as mnemonics. If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.
See also:
2023-12-16
Function gtk:button-new ()
Returns:
The newly created gtk:button widget.
Details:
Creates a new button. To add a child widget to the button, use the gtk:button-child function.
See also:
2023-9-2
Function gtk:button-new-with-label (label)
Arguments:
label -- a string with the text for the button
Returns:
The newly created gtk:button widget.
Details:
Creates a button with a label containing the given text.
See also:
2024-10-31
Function gtk:button-new-with-mnemonic (label)
Arguments:
label -- a string with the text of the button, with an underscore in front of the mnemonic character
Returns:
The new gtk:button widget.
Details:
Creates a new button widget containing a label with a mnemonic. If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.
See also:
2023-9-2
Function gtk:button-new-from-icon-name (name)
Arguments:
name -- a string with the icon name
Returns:
The new gtk:button widget displaying the themed icon.
Details:
Creates a new button containing an icon from the current icon theme. If the icon name is not known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.
See also:
2023-9-2

GtkToggleButton

Class gtk:toggle-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the toggle button should be pressed in.
Default value: false
group
The group property of type gtk:toggle-button (Write)
The toggle button whose group this widget belongs to.
Returned by:
Slot Access Functions:
Details:
The gtk:toggle-button widget is a gtk:button widget which will remain "pressed-in" when clicked. Clicking again will cause the toggle button to return to its normal state.

Figure: GtkToggleButton

A toggle button is created by calling either the gtk:toggle-button-new or gtk:toggle-button-new-with-label functions. If using the former, it is advisable to pack a widget, such as a gtk:label or a gtk:image widget, into the container of the toggle button. See the gtk:button documentation for more information.

The state of a gtk:toggle-button widget can be set and retrieved using the gtk:toggle-button-active function.

Grouping
Toggle buttons can be grouped together, to form mutually exclusive groups. Only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. To add a toggle button to a group, use the gtk:toggle-button-group function.
Examples:
In this example three toggle buttons are grouped together using the gtk:actionable API, by using the same action with parameter type and "s" state type for all buttons in the group, and giving each button its own target value.
(defun do-toggle-button-action (&optional application)
  (let* ((vbox (make-instance 'gtk:box
                              :orientation :vertical
                              :spacing 12
                              :margin-top 12
                              :margin-bottom 12
                              :margin-start 48
                              :margin-end 48))
         (window (make-instance 'gtk:window
                                :title "Toggle Buttons with Action"
                                :child vbox
                                :application application
                                :resizable nil))
         (label (make-instance 'gtk:label
                               :margin-top 9
                               :margin-bottom 6
                               :label "<b>Button ? is active</b>"
                               :use-markup t
                               :use-underline t))
         (action (g:simple-action-new-stateful "toggled"
                                               (g:variant-type-new "s")
                                               (g:variant-new-string "top")))
         (button nil))
    ;; Configure the "toggled" action
    (g:action-map-add-action application action)
    (g:signal-connect action "activate"
            (lambda (action parameter)
              (g:action-change-state action parameter)))
    (g:signal-connect action "change-state"
            (lambda (action parameter)
              (let ((str (g:variant-string parameter)))
                (cond ((string= str "top")
                       (setf (gtk:label-label label)
                             "<b>Button Top is active</b>"))
                      ((string= str "center")
                       (setf (gtk:label-label label)
                             "<b>Button Center is active</b>"))
                      (t
                       (setf (gtk:label-label label)
                             "<b>Button Bottom is active</b>")))
                (setf (g:action-state action) parameter))))
    ;; Create three grouped toggle buttons
    (setf button (gtk:toggle-button-new-with-mnemonic "Button _Top"))
    (gtk:actionable-set-detailed-action-name button "app.toggled::top")
    (gtk:box-append vbox button)
    ;; Create and add the second radio button to the group
    (setf button (gtk:toggle-button-new-with-mnemonic "Button _Center"))
    (gtk:actionable-set-detailed-action-name button "app.toggled::center")
    (gtk:box-append vbox button)
    ;; Create and add the third toggle button to the group
    (setf button (gtk:toggle-button-new-with-mnemonic "Button _Bottom"))
    (gtk:actionable-set-detailed-action-name button "app.toggled::bottom")
    (gtk:box-append vbox button)
    ;; Add a label which shows the status of the toggle buttons
    (gtk:box-append vbox label)
    ;; Make the "app.toggled::center" action active
    (g:action-activate (g:action-map-lookup-action application "toggled")
                       (g:variant-new-string "center"))
    ;; Present window
    (gtk:window-present window)))    
CSS nodes:
The gtk:toggle-button implementation has a single CSS node with name button. To differentiate it from a plain button, it gets the .toggle style class.
Signal Details:
The "toggled" signal
lambda (toggle)    :run-first      
toggle
The gtk:toggle-button widget which received the signal.
Should be connected if you wish to perform an action whenever the state of the toggle button is changed.
See also:
2024-11-3
Accessor gtk:toggle-button-active (object)
Syntax:
(gtk:toggle-button-active object) => active
(setf (gtk:toggle-button-active object) active)
Arguments:
object -- a gtk:toggle-button widget
active -- true if the toggle button should be pressed in
Details:
Accessor of the active slot of the gtk:toggle-button class. The gtk:toggle-button-active function queries a toggle button and returns its current state. Returns true if the toggle button is pressed in and false if it is raised. The (setf gtk:toggle-button-active) function sets the status of the toggle button.

If the status of the toggle button changes, this action causes the "toggled" signal to be emitted.
See also:
2024-5-4
Accessor gtk:toggle-button-group (object)
Syntax:
(setf (gtk:toggle-button-group object) group)
Arguments:
object -- a gtk:toggle-button widget
group -- another gtk:toggle-button widget to form a group with
Details:
Accessor of the group slot of the gtk:toggle-button class. The (setf gtk:toggle-button-group) function adds object to the group of group. In a group of multiple toggle buttons, only one button can be active at a time.

Note that the same effect can be achieved via the gtk:actionable API, by using the same action with parameter type and "s" state type for all buttons in the group, and giving each button its own target value.
See also:
2024-5-4
Function gtk:toggle-button-new ()
Returns:
The new gtk:toggle-button widget.
Details:
Creates a new toggle button. A widget should be packed into the toggle button, as in the gtk:button-new function.
See also:
2024-11-3
Function gtk:toggle-button-new-with-label (label)
Arguments:
label -- a string containing the message to be placed in the toggle button
Returns:
The new gtk:toggle-button widget.
Details:
Creates a new toggle button with a text label.
See also:
2024-5-4
Function gtk:toggle-button-new-with-mnemonic (label)
Arguments:
label -- a string with the text of the button, with an underscore in front of the mnemonic character
Returns:
The new gtk:toggle-button widget.
Details:
Creates a new toggle button containing a label. The label will be created using the gtk:label-new-with-mnemonic function, so underscores in label indicate the mnemonic for the button.
See also:
2024-5-4
Function gtk:toggle-button-toggled (button)
Arguments:
button -- a gtk:toggle-button widget
Details:
Emits the "toggled" signal on the toggle button.
Warning:
The gtk:toggle-button-toggled function is deprecated since 4.10. There is no good reason for an application ever to call this function.
See also:
2024-5-4

GtkCheckButton

Class gtk:check-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the check button should be pressed in.
Default value: false
child
The child property of type gtk:widget (Read / Write)
The child widget. Since 4.8
group
The group property of type gtk:check-button (Write)
The check button whose group this widget belongs to.
inconsistent
The inconsistent property of type :boolean (Read / Write)
Whether the check button is in an "in between" state.
Default value: false
label
The label property of type :string (Read / Write)
The text of the label widget inside the button, if the button contains a label widget.
Default value: nil
use-underline
The use-underline property of type :boolean (Read / Write)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:check-button widget places a label next to an indicator.

Figure: GtkCheckButton

The gtk:check-button widget is created by calling either the gtk:check-button-new or gtk:check-button-new-with-label functions. The state of a check button can be set specifically using the gtk:check-button-active function.

Inconsistent state
In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used, for example, when the user has selected a range of items, such as some text or spreadsheet cells, that are affected by a check button, and the current values in that range are inconsistent. To set a check button to inconsistent state, use the gtk:check-button-inconsistent function.

Grouping
Check buttons can be grouped together, to form mutually exclusive groups. Only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. Grouped check buttons use a different indicator, and are commonly referred to as radio buttons. To add a gtk:check-button widget to a group, use the gtk:check-button-group function.
Examples:
This example shows check and radio buttons.
(defun do-check-button (&optional application)
  (let* ((grid (make-instance 'gtk:grid
                              :column-spacing 24
                              :row-spacing 12
                              :halign :center
                              :margin-top 12
                              :margin-bottom 12
                              :margin-start 12
                              :margin-end 12))
         (window (make-instance 'gtk:window
                                :title "Check Buttons"
                                :child grid
                                :application application
                                :resizable nil))
         (group nil) (button nil))
    ;; Create three radio buttons and put the buttons into the grid
    (setf button (gtk:check-button-new-with-label "Radio 1"))
    (setf group button)
    (gtk:grid-attach grid button 0 0 1 1)
    ;; Create and add the second radio button to the group
    (setf button (gtk:check-button-new-with-label "Radio 2"))
    (setf (gtk:check-button-group button) group)
    (gtk:grid-attach grid button 0 1 1 1)
    ;; Make second radio button active
    (setf (gtk:check-button-active button) t)
    ;; Create and add the third radio button to the group
    (setf button (gtk:check-button-new-with-label "Radio 3"))
    (setf (gtk:check-button-group button) group)
    (gtk:grid-attach grid button 0 2 1 1)
    ;; Create three check buttons and put the buttons into the grid
    (gtk:grid-attach grid
                     (gtk:check-button-new-with-mnemonic "Check _1")
                     1 0 1 1)
    (gtk:grid-attach grid
                     (gtk:check-button-new-with-mnemonic "Check _2")
                       1 1 1 1)
    (gtk:grid-attach grid
                     (gtk:check-button-new-with-mnemonic "Check _3")
                     1 2 1 1)
    ;; Make first check button active
    (setf (gtk:check-button-active (gtk:grid-child-at grid 1 0)) t)
    ;; Present window
    (gtk:window-present window)))    
CSS nodes:
checkbutton[.text-button]
├── check
╰── [label]    
The gtk:check-button implementation has a main node with name checkbutton. If the label property is set, it contains a label child. The indicator node is named check when no group is set, and radio if the check button is grouped together with other check buttons.
Accessibility:
The gtk:check-button implementation uses the :checkbox role of the gtk:accessible-role enumeration.
Signal Details:
The "activated" signal
lambda (checkbutton)    :action      
checkbutton
The gtk:check-button widget which received the signal.
Emitted when the check button is activated. The signal is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the "toggled" signal. Since 4.2
The "toggled" signal
lambda (checkbutton)    :run-first      
checkbutton
The gtk:check-button widget which received the signal.
Emitted when the active property of the check button changes.
See also:
2024-5-4
Accessor gtk:check-button-active (object)
Syntax:
(gtk:check-button-active object) => active
(setf (gtk:check-button-active object) active)
Arguments:
object -- a gtk:check-button widget
active -- a boolean whether the check button should be pressed in
Details:
Accessor of the active slot of the gtk:check-button class. Setting the active property to true will add the :checked state to both the check button and the indicator CSS node.
See also:
2024-5-4
Accessor gtk:check-button-child (object)
Syntax:
(gtk:check-button-child object) => child
(setf (gtk:check-button-child object) child)
Arguments:
object -- a gtk:check-button widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:check-button class. The gtk:check-button-child function gets the child widget of the check button or nil if the label property is set. The (setf gtk:check-button-child) function sets the child widget.

Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for the check button. Most likely, you will either set the accessibility label or description for the check button explicitly, or you will set a labelled-by or described-by relations from the child widget to the check button.

Since 4.8
See also:
2024-5-4
Accessor gtk:check-button-group (object)
Syntax:
(setf (gtk:check-button-group object) group)
Arguments:
object -- a gtk:check-button widget
group -- a gtk:check-button widget
Details:
Accessor of the group slot of the gtk:check-button class. Adds the check button to the group of group. In a group of multiple check buttons, only one button can be active at a time.

Setting the group of a check button also changes the CSS name of the indicator widget's CSS node to radio. The behavior of a check button in a group is also commonly known as a "radio button".

Note that the same effect can be achieved via the gtk:actionable API, by using the same action with parameter type and "s" state type for all buttons in the group, and giving each button its own target value.
See also:
2024-5-4
Accessor gtk:check-button-inconsistent (object)
Syntax:
(gtk:check-button-inconsistent object) => inconsistent
(setf (gtk:check-button-inconsistent object) inconsistent)
Arguments:
object -- a gtk:check-button widget
inconsistent -- a boolean whether the check button is in an "in between" state
Details:
Accessor of the inconsistent slot of the gtk:check-button class. If the user has selected a range of elements, such as some text or spreadsheet cells, that are affected by a check button, and the current values in that range are inconsistent, you may want to display the toggle in an "in between" state. Normally you would turn off the inconsistent state again if the user checks the check button. This has to be done manually, the inconsistent property only affects visual appearance, not the semantics of the button.
See also:
2024-5-4
Accessor gtk:check-button-label (object)
Syntax:
(gtk:check-button-label object) => label
(setf (gtk:check-button-label object) label)
Arguments:
object -- a gtk:check-button widget
label -- a string with the text of the label widget inside the button
Details:
Accessor of the label slot of the gtk:check-button class. The gtk:check-button-label function returns the label of the check button or nil if the child property is set. The (setf gtk:check-button-label) function sets the text. If the use-underline property is true, an underscore in label is interpreted as mnemonic indicator, see the gtk:check-button-use-underline function for details on this behavior.
See also:
2024-11-3
Accessor gtk:check-button-use-underline (object)
Syntax:
(gtk:check-button-use-underline object) => setting
(setf (gtk:check-button-use-underline object) setting)
Arguments:
object -- a gtk:check-button widget
setting -- a boolean whether an underline in the text indicates the next character should be used for the mnemonic accelerator key
Details:
Accessor of the use-underline slot of the gtk:check-button class. The gtk:check-button-use-underline function returns whether underlines in the label indicate mnemonics. The (setf gtk:check-button-use-underline) function sets whether underlines in the label indicate mnemonics.

If the setting is true, an underscore character indicates a mnemonic accelerator key. This behavior is similar to the use-underline property of the gtk:label widget.
See also:
2024-5-14
Function gtk:check-button-new ()
Returns:
The new gtk:check-button widget.
Details:
Creates a new check button.
See also:
2024-11-3
Function gtk:check-button-new-with-label (label)
Arguments:
label -- a string with the text for the check button
Returns:
The new gtk:check-button widget.
Details:
Creates a new check button with a gtk:label widget to the right of it.
See also:
2024-11-3
Function gtk:check-button-new-with-mnemonic (label)
Arguments:
label -- a string with the text of the button, with an underscore in front of the mnemonic character
Returns:
The new gtk:check-button widget.
Details:
Creates a new check button widget with a gtk:label widget to the right of it. The label will be created using the gtk:label-new-with-mnemonic function, so underscores in label indicate the mnemonic for the check button.
See also:
2024-11-3

GtkMenuButton

GEnum gtk:arrow-type
Declaration:
(gobject:define-genum "GtkArrowType" arrow-type
  (:export t
   :type-initializer "gtk_arrow_type_get_type")
  (:up 0)
  (:down 1)
  (:left 2)
  (:right 3)
  (:none 4))  
Values:
:up
Represents an upward pointing arrow.
:down
Represents a downward pointing arrow.
:left
Represents a left pointing arrow.
:right
Represents a right pointing arrow.
:none
No arrow.
Details:
Used to indicate the direction in which an arrow should point in a gtk:menu-button widget.
See also:
2024-4-20
Class gtk:menu-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the menu button is active. Since 4.10
Default value: false
always-show-arrow
The always-show-arrow property of type :boolean (Read / Write)
Whether to show a dropdown arrow even when using an icon or a custom child. Since 4.4
Default value: false
can-shrink
The can-shrink property of type :boolean (Read / Write)
Whether the size of the menu button can be made smaller than the natural size of its contents. Since 4.12
Default value: false
child
The child property of type gtk:widget (Read / Write)
The child widget. Since 4.6
direction
The direction property of type gtk:arrow-type (Read / Write)
The arrow type representing the direction in which the menu or popover will be popped out.
Default value: :down
has-frame
The has-frame property of type :boolean (Read / Write)
Whether the button has a frame.
Default value: true
icon-name
The icon-name property of type :string (Read / Write)
The name of the icon used to automatically populate the button.
Default value: nil
label
The label property of type :string (Read / Write)
The label for the button.
Default value: nil
menu-model
The menu-model property of type g:menu-model (Read / Write)
The menu model from which the popup will be created. See the gtk:menu-button-menu-model function for the interaction with the popover property.
popover
The popover property of type gtk:popover (Read / Write)
The popover that will be popped up when the button is clicked.
primary
The primary property of type :boolean (Read / Write)
Whether the menu button acts as a primary menu. Primary menus can be opened using the F10 key. Since 4.4
Default value: false
use-underline
The use-underline property of type :boolean (Read / Write)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:menu-button widget is used to display a popup when clicked on. This popup can be provided either as a gtk:popover widget or as an abstract g:menu-model object.

Figure: GtkMenuButton

The gtk:menu-button widget can show either an icon, set with the icon-name property, or a label, set with the label property. If neither is explicitly set, a gtk:image widget is automatically created, using an arrow image oriented according to the direction property or the generic "open-menu-symbolic" icon if the direction is not set.

The positioning of the popup is determined by the direction property of the menu button.

For menus, the halign and valign properties of the menu are also taken into account. For example, when the direction is :down and the horizontal alignment is :start, the menu will be positioned below the button, with the starting edge, depending on the text direction, of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is "pushed in".
CSS nodes:
 menubutton
 ╰── button.toggle
     ╰── <content>
          ╰── [arrow]    
The gtk:menu-button implementation has a single CSS node with name menubutton which contains a button node with a .toggle style class.

If the menu button contains an icon, it will have the .image-button style class, if it contains text, it will have the .text-button style class. If an arrow is visible in addition to an icon, text or a custom child widget, it will also have the .arrow-button style class.

Inside the toggle button content, there is an arrow node for the indicator, which will carry one of the .none, .up, .down, .left or .right style classes to indicate the direction that the menu will appear in. The CSS is expected to provide a suitable image for each of these cases using the -gtk-icon-source property.

Optionally, the menubutton node can carry the .circular style class to request a round appearance.
Accessibility:
The gtk:menu-button implementation uses the :button role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (button)    :action      
button
The gtk:button widget which received the signal.
The signal on the gtk:menu-button widget is an action signal and emitting it causes the button to pop up its menu. Since 4.4
See also:
2024-5-4
Accessor gtk:menu-button-active (object)
Syntax:
(gtk:menu-button-active object) => active
(setf (gtk:menu-button-active object) active)
Arguments:
object -- a gtk:menu-button widget
active -- a boolean whether the menu button is active
Details:
Accessor of the active slot of the gtk:menu-button class. The gtk:menu-button-active function returns whether the menu button is active. The (setf gtk:menu-button-active) function sets the property.

Since 4.10
See also:
2024-4-20
Accessor gtk:menu-button-always-show-arrow (object)
Syntax:
(gtk:menu-button-always-show-arrow object) => setting
(setf (gtk:menu-button-always-show-arrow object) setting)
Arguments:
object -- a gtk:menu-button widget
setting -- a boolean whether to show a dropdown arrow even when using an icon or a custom child
Details:
Accessor of the always-show-arrow slot of the gtk:menu-button class. The gtk:menu-button-always-show-arrow function gets whether to show a dropdown arrow even when using an icon. The (setf gtk:menu-button-always-show-arrow) function sets the property.

Since 4.4
See also:
2024-4-20
Accessor gtk:menu-button-child (object)
Syntax:
(gtk:menu-button-child object) => child
(setf (gtk:menu-button-child object) child)
Arguments:
object -- a gtk:menu-button widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:menu-button class. The gtk:menu-button-child function gets the child widget. The (setf gtk:menu-button-child) function sets the child widget.

Setting a child widget resets the label and icon-name properties. If the always-show-arrow property is set to true and the direction property is not :none, a dropdown arrow will be shown next to the child widget.

Since 4.6
See also:
2024-4-20
Accessor gtk:menu-button-direction (object)
Syntax:
(gtk:menu-button-direction object) => direction
(setf (gtk:menu-button-direction object) direction)
Arguments:
object -- a gtk:menu-button widget
direction -- a value of the gtk:arrow-type enumeration
Details:
Accessor of the direction slot of the gtk:menu-button class. The gtk:menu-button-direction function returns the direction the popup will be pointing at when popped up. The (setf gtk:menu-button-direction) function sets the direction in which the popup will be popped up, as well as changing the direction of the arrow. The child widget will not be changed to an arrow if it was customized.

If the popup does not fit in the available space in the given direction, GTK will its best to keep it inside the screen and fully visible.

If you pass the :none value for a direction, the popup will behave as if you passed the :down value, although you will not see any arrows.
See also:
2024-4-20
Accessor gtk:menu-button-has-frame (object)
Syntax:
(gtk:menu-button-has-frame object) => setting
(setf (gtk:menu-button-has-frame object) setting)
Arguments:
object -- a gtk:menu-button widget
setting -- a boolean whether the button has a frame
Details:
Accessor of the has-frame slot of the gtk:menu-button class. The gtk:menu-button-has-frame function returns whether the button has a frame. The (setf gtk:menu-button-has-frame) function sets the style of the button.
See also:
2024-4-20
Accessor gtk:menu-button-icon-name (object)
Syntax:
(gtk:menu-button-icon-name object) => name
(setf (gtk:menu-button-icon-name object) name)
Arguments:
object -- a gtk:menu-button widget
name -- a string with the name of the icon
Details:
Accessor of the icon-name slot of the gtk:menu-button class. The gtk:menu-button-icon-name function gets the name of the icon shown in the button. The (setf gtk:menu-button-icon-name) function sets the name of the icon.
See also:
2024-4-20
Accessor gtk:menu-button-label (object)
Syntax:
(gtk:menu-button-label object) => label
(setf (gtk:menu-button-label object) label)
Arguments:
object -- a gtk:menu-button widget
label -- a string with the label
Details:
Accessor of the label slot of the gtk:menu-button class. The gtk:menu-button-label function gets the label shown in the button. The (setf gtk:menu-button-label) function sets the label.
See also:
2024-4-20
Accessor gtk:menu-button-menu-model (object)
Syntax:
(gtk:menu-button-menu-model object) => model
(setf (gtk:menu-button-menu-model object) model)
Arguments:
object -- a gtk:menu-button widget
model -- a g:menu-model object, or nil to unset and disable the button
Details:
Accessor of the menu-model slot of the gtk:menu-button class. The gtk:menu-button-menu-model function returns the menu model used to generate the popup. The (setf gtk:menu-button-menu-model) function sets the menu model from which the popup will be constructed, or nil to dissociate any existing menu model and disable the button.

A gtk:popover widget will be created from the menu model with the gtk:popover-menu-new-from-model function. Actions will be connected as documented for this function.

If the popover property is already set, it will be dissociated from the menu button, and the property is set to nil.
See also:
2024-4-20
Accessor gtk:menu-button-popover (object)
Syntax:
(gtk:menu-button-popover object) => popover
(setf (gtk:menu-button-popover object) popover)
Arguments:
object -- a gtk:menu-button widget
popover -- a gtk:popover widget, or nil to unset and disable the button
Details:
Accessor of the popover slot of the gtk:menu-button class. The gtk:menu-button-popover function returns the popover that pops out of the button. If the button is not using a popover, this function returns nil. The (setf gtk:menu-button-popover) function sets the popover that will be popped up when the menu button is clicked, or nil to dissociate any existing popover and disable the button.

If the menu-model property is set, the menu model is dissociated from the menu button, and the property is set to nil.
See also:
2024-4-20
Accessor gtk:menu-button-primary (object)
Syntax:
(gtk:menu-button-primary object) => setting
(setf (gtk:menu-button-primary object) setting)
Arguments:
object -- a gtk:menu-button widget
setting -- a boolean whether the menu button acts as a primary menu
Details:
Accessor of the primary slot of the gtk:menu-button class. The gtk:menu-button-primary function returns whether the menu button acts as a primary menu. The (setf gtk:menu-button-primary) function sets the property. Primary menus can be opened with the F10 key.

Since 4.4
See also:
2024-5-14
Accessor gtk:menu-button-use-underline (object)
Syntax:
(gtk:menu-button-use-underline object) => setting
(setf (gtk:menu-button-use-underline object) setting)
Arguments:
object -- a gtk:menu-button widget
setting -- a boolean whether underlines in the text indicates mnemonics
Details:
Accessor of the use-underline slot of the gtk:menu-button class. The gtk:menu-button-use-underline function returns whether an embedded underline in the text indicates a mnemonic. The (setf gtk:menu-button-use-underline) function sets the property.
See also:
2024-4-20
Function gtk:menu-button-new ()
Returns:
The new gtk:menu-button widget.
Details:
Creates a new menu button with downwards pointing arrow as the only child. You can replace the child widget with another widget should you wish to.
See also:
2024-4-20
Function gtk:menu-button-popup (button)
Arguments:
button -- a gtk:menu-button widget
Details:
Pop up the menu.
See also:
2024-5-4
Function gtk:menu-button-popdown (button)
Arguments:
button -- a gtk:menu-button widget
Details:
Dismiss the menu.
See also:
2024-5-4
Callback gtk:menu-button-create-popup-func
Syntax:
lambda (button)
Arguments:
button -- a gtk:menu-button widget
Details:
User-provided callback function to create a popup for button on demand. This function is called when the popup of the menu button is shown, but none has been provided by the gtk:menu-button-popover or gtk:menu-button-menu-model functions.
See also:
2024-11-3
Function gtk:menu-button-set-create-popup-func (button func)
Arguments:
button -- a gtk:menu-button widget
func -- a gtk:menu-button-create-popup-func callback function to call when a popup is about to be shown, but none has been provided by other means, or nil to reset to default behavior
Details:
Sets func to be called when a popup is about to be shown. The callback function should use one of the gtk:menu-button-popover or gtk:menu-button-menu-model functions to set a popup for the menu button. If func is non-nil, the menu button will always be sensitive.

Using this function will not reset the menu widget attached to the menu button. Instead, this can be done manually in the callback function.
See also:
2024-11-3

GtkLinkButton

Superclasses:
Documented Subclasses:
None
Direct Slots:
uri
The uri property of type :string (Read / Write)
The URI bound to this button.
Default value: nil
visited
The visited property of type :boolean (Read / Write)
The visited state of this button. A visited link is drawn in a different color.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:link-button widget is a gtk:button widget with a hyperlink, similar to the one used by web browsers, which triggers an action when clicked. It is useful to show quick links to resources. A link button is created by calling either the gtk:link-button-new or gtk:link-button-new-with-label function. If using the former, the URI you pass to the constructor is used as a label for the widget.

Figure: GtkLinkButton

The URI bound to a gtk:link-button widget can be set specifically or retrieved using the gtk:link-button-uri function.

By default, the gtk:link-button widget calls the gtk:file-launcher-launch function when the button is clicked. This behaviour can be overridden by connecting to the "activate-link" signal and returning true from the signal handler.
CSS nodes:
The gtk:link-button implementation has a single CSS node with name button. To differentiate it from a plain gtk:button widget, it gets the .link style class.
Accessibility:
The gtk:link-button implementation uses the :link role of the gtk:accessible-role enumeration.
Signal Details:
The "activate-link" signal
lambda (button)    :run-last      
button
The gtk:link-button widget that emitted the signal.
The signal is emitted each time the link button has been clicked. The default handler will call the gtk:file-launcher-launch function with the URI stored inside the uri property. To override the default behavior, you can connect to the "activate-link" signal and stop the propagation of the signal by returning true from your handler.
See also:
2025-2-22
Syntax:
(gtk:link-button-uri object) => uri
(setf (gtk:link-button-uri object) uri)
Arguments:
object -- a gtk:link-button widget
uri -- a string for a valid URI
Details:
Accessor of the uri slot of the gtk:link-button class. The gtk:link-button-uri function retrieves the URI. The (setf gtk:link-button-uri) function sets uri as the URI where the link button points. As a side-effect this unsets the visited state of the button.
See also:
2025-2-22
Syntax:
(gtk:link-button-visited object) => visited
(setf (gtk:link-button-visited object) visited)
Arguments:
object -- a gtk:link-button widget
visited -- a boolean for the "visited" state
Details:
Accessor of the visited slot of the gtk:link-button class. The gtk:link-button-visited function retrieves the "visited" state of the URI where the link button points. The (setf gtk:link-button-visited) function sets the "visited" state of the URI.

The button becomes visited when it is clicked. If the URI is changed on the button, the visited state is unset again.
See also:
2025-2-22
Arguments:
uri -- a string for a valid URI
Returns:
The new gtk:link-button widget.
Details:
Creates a new link button with the URI as its text.
See also:
2025-2-22
Arguments:
uri -- a string for a valid URI
label -- a string for the text of the button
Returns:
The new gtk:link-button widget.
Details:
Creates a new link button containing a label.
See also:
2025-2-22

GtkScaleButton

Class gtk:scale-button
Superclasses:
Documented Subclasses:
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the scale button should be pressed in.
Default value: false
adjustment
The adjustment property of type gtk:adjustment (Read / Write)
The adjustment that contains the current value of the scale button.
has-frame
The has-frame property of type gboolean (Read / Write)
Whether the scale button has a frame. Since 4.14
Default value: false
icons
The icons property of type g:strv-t (Read / Write)
The names of the icons to be used by the scale button. The first item in the list will be used in the button when the current value is the lowest value, the second item for the highest value. All the subsequent icons will be used for all the other values, spread evenly over the range of values. If there is only one icon name in the icons list, it will be used for all the values. If only two icon names are in the icons array, the first one will be used for the bottom 50% of the scale, and the second one for the top 50%. It is recommended to use at least 3 icons so that the scale button reflects the current value of the scale better for the users.
value
The value property of type :double (Read / Write)
The value of the scale.
Default value: 0.0d0
Returned by:
Slot Access Functions:
Details:
The gtk:scale-button widget provides a button which pops up a scale widget. This kind of widget is commonly used for volume controls in multimedia applications.
CSS nodes:
The gtk:scale-button implementation has a single CSS node with name scalebutton. To differentiate it from a plain gtk:button widget, it gets the .scale style class.
Signal Details:
The "popdown" signal
lambda (button)    :action      
button
The gtk:scale-button widget which received the signal.
The signal is a keybinding signal which gets emitted to popdown the scale widget. The default binding for this signal is the Escape key.
The "popup" signal
lambda (button)    :action      
button
The gtk:scale-button widget which received the signal.
The signal is a keybinding signal which gets emitted to popup the scale widget. The default bindings for this signal are the Space, Enter and Return keys.
The "value-changed" signal
lambda (button value)    :run-last      
button
The gtk:scale-button widget which received the signal.
value
The double float with the new value.
The signal is emitted when the value field has changed.
2024-5-7
Accessor gtk:scale-button-active (object)
Syntax:
(gtk:scale-button-active object object) => active
Arguments:
object -- a gtk:scale-button widget
active -- a boolean whether the scale button should be pressed in
Details:
Accessor of the active slot of the gtk:scale-button class. The gtk:scale-button-active function queries a scale button and returns its current state. Returns true if the scale button is pressed in and false if it is raised.

Since: 4.10
See also:
2024-5-7
Accessor gtk:scale-button-adjustment (object)
Syntax:
(gtk:scale-button-adjustment object object) => adjustment
(setf (gtk:scale-button-adjustment object) adjustment)
Arguments:
object -- a gtk:scale-button widget
adjustment -- a gtk:adjustment object
Details:
Accessor of the adjustment slot of the gtk:scale-button class. The gtk:scale-button-adjustment function gets the adjustment associated with the scale button. The (setf gtk:scale-button-adjustment) function sets the adjustment.
See also:
2024-5-7
Accessor gtk:scale-button-has-frame (object)
Syntax:
(gtk:scale-button-has-frame object object) => setting
(setf (gtk:scale-button-has-frame object) setting)
Arguments:
object -- a gtk:scale-button widget
setting -- a boolean whether the scale button has a frame
Details:
Accessor of the has-frame slot of the gtk:scale-button class. The gtk:scale-button-has-frame function returns whether the scale button has a frame. The (setf gtk:scale-button-has-frame) function sets the style of the scale button.

Since 4.14
See also:
2024-5-26
Accessor gtk:scale-button-icons (object)
Syntax:
(gtk:scale-button-icons object object) => icons
(setf (gtk:scale-button-icons object) icons)
Arguments:
object -- a gtk:scale-button widget
icons -- a list of strings with the icon names
Details:
Accessor of the icons slot of the gtk:scale-button class. The (setf gtk:scale-button-icons) function sets the icons to be used by the scale button.

The names of the icons to be used by the scale button. The first item in the list will be used in the button when the current value is the lowest value, the second item for the highest value. All the subsequent icons will be used for all the other values, spread evenly over the range of values. If there is only one icon name in the icons list, it will be used for all the values. If only two icon names are in the icons array, the first one will be used for the bottom 50% of the scale, and the second one for the top 50%. It is recommended to use at least 3 icons so that the scale button reflects the current value of the scale better for the users.
See also:
2024-5-7
Accessor gtk:scale-button-value (object)
Syntax:
(gtk:scale-button-value object) => value
(setf (gtk:scale-button-value object) value)
Arguments:
object -- a gtk:scale-button widget
value -- a double float with the value of the scale button
Details:
Accessor of the value slot of the gtk:scale-button class. The gtk:scale-button-value function gets the current value of the scale button. The (setf gtk:scale-button-value) function sets the current value.

If the value is outside the minimum or maximum values of the scale button adjustment, it will be clamped to fit inside them. The scale button emits the "value-changed" signal if the value changes.
See also:
2024-11-3
Function gtk:scale-button-new (min max step icons)
Arguments:
min -- a double float with the minimum value of the scale
max -- a double float with the maximum value of the scale
step -- a double float with the stepping of the value when a scroll wheel event, or up/down arrow event occurs
icons -- a list of strings with the icon names, or nil if you want to set the list later with the gtk:scale-button-icons function
Returns:
The new gtk:scale-button widget.
Details:
Creates a scale button, with a range between min and max, with a stepping of step.
See also:
2024-5-7
Function gtk:scale-button-popup (button)
Arguments:
button -- a gtk:scale-button widget
Returns:
The gtk:widget widget for the popup of the scale button.
Details:
Retrieves the popup of the scale button.
See also:
2024-11-3
Function gtk:scale-button-plus-button (button)
Arguments:
button -- a gtk:scale-button widget
Returns:
The gtk:widget widget for the plus button of the scale button.
Details:
Retrieves the plus button of the scale button.
See also:
2024-11-3
Function gtk:scale-button-minus-button (button)
Arguments:
button -- a gtk:scale-button widget
Returns:
The gtk:widget widget for the minus button of the scale button.
Details:
Retrieves the minus button of the scale button.
See also:
2024-11-3

GtkSwitch

Class gtk:switch
Superclasses:
Documented Subclasses:
None
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the switch is in its on or off state.
Default value: false
state
The state property of type :boolean (Read / Write)
The backend state that is controlled by the switch. See the "state-set" signal for details.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:switch widget is a widget that has two states: on or off.

Figure: GtkSwitch

The user can control which state should be active by clicking the switch, or by dragging the handle.

The gtk:switch widget can also handle situations where the underlying state changes with a delay. See the "state-set" signal for details.
CSS nodes:
 switch
 ├── label
 ├── label
 ╰── slider    
The gtk:switch implementation has four CSS nodes, the main node with the name switch and subnodes for the slider and the on and off labels. Neither of them is using any style classes.
Accessibility:
The gtk:switch implementation uses the :switch role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (widget)    :action      
widget
The gtk:switch widget which received the signal.
The signal on the switch is an action signal and emitting it causes the switch to animate. Applications should never connect to this signal, but use the "notify::active" signal.
The "state-set" signal
lambda (widget state)    :run-last      
widget
The gtk:switch widget which received the signal.
state
The boolean with the state of the switch.
Returns
True to stop the signal emission.
The signal on the switch is emitted to change the underlying state. It is emitted when the user changes the switch position. The default handler keeps the state in sync with the active property.

To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call the gtk:switch-state function when the underlying state change is complete. The signal handler should return true to prevent the default handler from running.

Visually, the underlying state is represented by the trough color of the switch, while the active property is represented by the position of the switch.
See also:
2025-2-22
Accessor gtk:switch-active (object)
Syntax:
(gtk:switch-active object) => active)
(setf (gtk:switch-active object) active)
Arguments:
object -- a gtk:switch widget
active -- true if the switch should be active, and false otherwise
Details:
Accessor of the active slot of the gtk:switch class. The gtk:switch-active function gets whether the switch is in its "on" or "off" state. The (setf gtk:switch-active) function changes the state of the switch to the desired one.
See also:
2025-2-22
Accessor gtk:switch-state (object)
Syntax:
(gtk:switch-state object) => state)
(setf (gtk:switch-state object) state)
Arguments:
object -- a gtk:switch widget
state -- a boolean with the state
Details:
Accessor of the state slot of the gtk:switch class. The gtk:switch-active function gets the underlying state of the switch. The (setf gtk:switch-active) function sets the underlying state.

Normally, this is the same as the active property, unless the switch is set up for delayed state changes. This function is typically called from a "state-set" signal handler.
See also:
2025-2-22
Function gtk:switch-new ()
Returns:
The newly created gtk:switch widget.
Details:
Creates a new switch.
See also:
2025-2-22

Numeric and Text Data Entry

GtkEditable

Interface gtk:editable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
cursor-position
The cursor-position property of type :int (Read)
The current position of the insertion cursor in chars.
Allowed values: [0, 65535]
Default value: 0
editable
The editable property of type :boolean (Read / Write)
Whether the contents of the editable widget can be edited.
Default value: true
enable-undo
The enable-undo property of type :boolean (Read / Write)
Whether undo/redo should be enabled for the editable widget.
Default value: true
max-width-chars
The max-width-chars property of type :int (Read / Write)
The desired maximum width of the editable widget, in characters.
Allowed values: >= -1
Default value: -1
selection-bound
The selection-bound property of type :int (Read)
The position of the opposite end of the selection from the cursor in chars.
Allowed values: [0, 65535]
Default value: 0
text
The text property of type :string (Read / Write)
The contents of the editable widget.
Default value: ""
width-chars
The width-chars property of type :int (Read / Write)
The number of characters to leave space for in the editable widget.
Allowed values: >= -1
Default value: -1
xalign
The xalign property of type :float (Read / Write)
The horizontal alignment, from 0.0 (left) to 1.0 (right). Reversed for RTL layouts.
Allowed values: [0.0, 1.0]
Default value: 0.0
Details:
The gtk:editable interface is an interface which should be implemented by text editing widgets, such as the gtk:entry and gtk:spin-button widgets. It contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to to modify the behavior of an editable widget.
Examples:
As an example of the latter usage, by connecting the following handler to the "insert-text" signal, an application can convert all entry into an editable widget into uppercase.
;; Handler for the "insert-text" signal
(setf handlerid
      (g:signal-connect entry "insert-text"
          (lambda (editable text length position)
            (g:signal-handler-block editable handlerid)
            (gtk:editable-insert-text editable
                                      (string-upcase text)
                                      (cffi:mem-ref position :intptr))
            (g:signal-stop-emission editable "insert-text")
            (g:signal-handler-unblock editable handlerid))))    
Signal Details:
The "changed" signal
lambda (editable)    :run-last      
editable
The gtk:editable widget which received the signal.
The signal is emitted at the end of a single user visible operation on the contents of the editable widget. For example, a paste operation that replaces the contents of the selection will cause only one signal emission, even though it is implemented by first deleting the selection, then inserting the new content, and may cause multiple "notify::text" signals to be emitted.
The "delete-text" signal
lambda (editable start end)    :run-last      
editable
The gtk:editable widget which received the signal.
start
The integer with the start position.
end
The integer with the end position.
The signal is emitted when text is deleted from the editable widget by the user. The default handler for this signal will normally be responsible for deleting the text, so by connecting to this signal and then stopping the signal with the g:signal-stop-emission function, it is possible to modify the range of deleted text, or prevent it from being deleted entirely. The start and end parameters are interpreted as for the gtk:editable-delete-text function.
The "insert-text" signal
lambda (editable text length position)    :run-last      
editable
The gtk:editable widget which received the signal.
text
The string with the new text to insert.
length
The integer with the length of the new text, in bytes, or -1 if text is null-terminated.
position
The pointer to an integer with the position, in characters, at which to insert the new text. This is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text. You get the Lisp value of position with the call (cffi:mem-ref position :intptr).
The signal is emitted when text is inserted into the editable widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with the g:signal-stop-emission function, it is possible to modify the inserted text, or prevent it from being inserted entirely.
See also:
2024-5-17
Accessor gtk:editable-cursor-position (object)
Syntax:
(gtk:editable-cursor-position object) => position
(setf (gtk:editable-cursor-position object) position)
Arguments:
object -- a gtk:editable widget
position -- an integer with the current cursor position
Details:
Accessor of the cursor-position slot of the gtk:editable class. The current position of the insertion cursor in chars.
See also:
2023-10-24
Accessor gtk:editable-editable (object)
Syntax:
(gtk:editable-editable object) => setting
(setf (gtk:editable-editable object) setting)
Arguments:
object -- a gtk:editable widget
setting -- a boolean whether the user is allowed to edit the text in the widget
Details:
Accessor of the editable slot of the gtk:editable class. The gtk:editable-editable function retrieves whether object is editable. The (setf gtk:editable-editable) function determines if the user can edit the text in the editable widget or not.
See also:
2023-10-24
Accessor gtk:editable-enable-undo (object)
Syntax:
(gtk:editable-enable-undo object) => setting
(setf (gtk:editable-enable-undo object) setting)
Arguments:
object -- a gtk:editable widget
setting -- a boolean whether undo is enabled
Details:
Accessor of the enable-undo slot of the gtk:editable class. The gtk:editable-enable-undo function gets whether undo/redo actions are enabled for the editable widget. The (setf gtk:editable-enable-undo) function sets the property.

If enabled, changes to the editable widget will be saved for undo/redo actions. This results in an additional copy of text changes and are not stored in secure memory. As such, undo is forcefully disabled when the visibility property of the gtk:text widget is set to false.
See also:
2024-11-15
Accessor gtk:editable-max-width-chars (object)
Syntax:
(gtk:editable-max-width-chars object) => max
(setf (gtk:editable-max-width-chars object) max)
Arguments:
object -- a gtk:editable widget
max -- an integer with the maximum width of the editable widget, in characters
Details:
Accessor of the max-width-chars slot of the gtk:editable class. The gtk:editable-max-width-chars function retrieves the desired maximum width of the editable widget, in characters. The (setf gtk:editable-max-width-chars) function sets the desired maximum width.
See also:
2023-10-24
Accessor gtk:editable-selection-bound (object)
Syntax:
(gtk:editable-selection-bound object) => end
(setf (gtk:editable-selection-bound object) end)
Arguments:
object -- a gtk:editable widget
end -- an integer with the position of the opposite end of the selection from the cursor in chars
Details:
Accessor of the selection-bound slot of the gtk:editable class. The position of the opposite end of the selection from the cursor in chars.
See also:
2023-10-24
Accessor gtk:editable-text (object)
Syntax:
(gtk:editable-text object) => text
(setf (gtk:editable-text object) text)
Arguments:
object -- a gtk:editable widget
text -- a string with the contents of the editable widget
Details:
Accessor of the text slot of the gtk:editable class. The gtk:editable-text function retrieves the contents of the editable widget. The (setf gtk:editable-text) function sets the text in the editable widget to the given value, replacing the current contents.
See also:
2023-10-24
Accessor gtk:editable-width-chars (object)
Syntax:
(gtk:editable-width-chars object) => width
(setf (gtk:editable-width-chars object) width)
Arguments:
object -- a gtk:editable widget
width -- an integer with the width in chars
Details:
Accessor of the width-chars slot of the gtk:editable class. The gtk:editable-width-chars function gets the value of the width in chars. The (setf gtk:editable-width-chars) function changes the size request of the editable widget to be about the right size for width characters.

Note that it changes the size request, the size can still be affected by how you pack the widget into containers. If the width argument is -1, the size reverts to the default size.
See also:
2023-10-24
Accessor gtk:editable-xalign (object)
Syntax:
(gtk:editable-xalign object) => align
(setf (gtk:editable-xalign object) align)
Arguments:
object -- a gtk:editable widget
align -- a single float with the horizontal alignmemnt
Details:
Accessor of the xalign slot of the gtk:editable class. The horizontal alignment, from 0.0 (left) to 1.0 (right). Reversed for RTL layouts.
See also:
2023-10-24
Function gtk:editable-chars (editable &key start end)
Arguments:
editable -- a gtk:editable object
start -- an integer with the start position, the default value is 0
end -- an integer with the end position, the default value is -1
Returns:
The string with a sequence of characters from the editable widget.
Details:
Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from the start position up to, but not including the end position. If the end position is negative, then the characters retrieved are those characters from the start position to the end position of the text. Note that positions are specified in characters, not bytes.
See also:
2024-11-15
Function gtk:editable-insert-text (editable text position)
Arguments:
editable -- a gtk:editable widget
text -- a string with the text to insert
position -- an integer with the position where text is inserted
Returns:
The integer with the position after the newly inserted text.
Details:
Inserts text into the contents of the editable widget, at position position. Note that the position value is in characters, not in bytes. The function returns the position after the newly inserted text.
See also:
2024-5-17
Function gtk:editable-delete-text (editable &key start end)
Arguments:
editable -- a gtk:editable widget
start -- an integer with the start position, the default value is 0
end -- an integer with the end position, the default value is -1
Details:
Deletes a sequence of characters. The characters that are deleted are those characters at positions from the start position up to, but not including the end position. If the end position is negative, then the characters deleted are those from the start position to the end of the text. Note that the positions are specified in characters, not bytes.
See also:
2023-10-24
Function gtk:editable-selection-bounds (editable)
Arguments:
editable -- a gtk:editable widget
Returns:
start -- an integer with the start position
end -- an integer with the end position
Details:
Retrieves the selection bounds of the editable widget. The start value will be filled with the start position of the selection and the end value with the end position. If no text was selected nil will be returned. Note that positions are specified in characters, not bytes.
See also:
2023-10-24
Function gtk:editable-select-region (editable &key start end)
Arguments:
editable -- a gtk:editable widget
start -- an integer with the start position of the region, the default value is 0
end -- an integer with the end position of the region, the default value is -1
Details:
Selects a region of text. The characters that are selected are those characters at positions from the start position up to, but not including the end position. If the end position is negative, then the the characters selected are those characters from the start position to the end position of the text. Note that positions are specified in characters, not bytes.
See also:
2024-11-15
Function gtk:editable-delete-selection (editable)
Arguments:
editable -- a gtk:editable widget
Details:
Deletes the currently selected text of the editable widget. This call does not do anything if there is no selected text.
See also:
2023-10-24
Function gtk:editable-position (editable)
Syntax:
(gtk:editable-position editable) => position
(setf (gtk:editable-position editable) position)
Arguments:
editable -- a gtk:editable widget
position -- an integer with the position of the cursor, in chars
Details:
The gtk:editable-position function retrieves the current position of the cursor relative to the start of the content of the editable widget. The (setf gtk:editable-position) function sets the cursor position in the editable widget to the given value.

The cursor is displayed before the character with the given (base 0) index in the contents of the editable widget. The value must be less than or equal to the number of characters in the editable widget. A value of -1 indicates that the position should be set after the last character of the editable. Note that position is in characters, not in bytes.
See also:
2024-11-15
Function gtk:editable-alignment (editable)
Syntax:
(gtk:editable-alignment editable) => align
(setf (gtk:editable-alignment editable) align)
Arguments:
editable -- a gtk:editable widget
align -- a number coerced to a single float with the horizontal alignment, from 0.0 (left) to 1.0 (right), reversed for RTL layouts
Details:
The gtk:editable-alignment function gets the value of the horizontal alignment of the editable widget. The (setf gtk:editable-alignment) function sets the alignment. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the editable widget.
Notes:
This function is equivalent to the gtk:editable-xalign function. The Lisp implementation calls the corresponding gtk:editable-xalign functions.
See also:
2024-11-15

GtkEntryBuffer

Class gtk:entry-buffer
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
length
The length property of type :uint (Read)
The length, in characters, of the text in the entry buffer.
Allowed values: <= 65535
Default value: 0
max-length
The max-length property of type :int (Read / Write)
The maximum length, in characters, of the text in the entry buffer.
Allowed values: [0,65535]
Default value: 0
text
The text property of type :string (Read / Write)
The contents of the entry buffer.
Default value: ""
Returned by:
Slot Access Functions:
Details:
The gtk:entry-buffer object contains the actual text displayed in a gtk:entry widget. A single gtk:entry-buffer object can be shared by multiple gtk:entry widgets which will then share the same text content, but not the cursor position, visibility attributes, icon, and so on.

The gtk:entry-buffer class may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an undo/redo concept of the application.
Signal Details:
The "deleted-text" signal
lambda (buffer pos nchars)    :run-first      
buffer
The gtk:entry-buffer object.
pos
The integer with the position the text was deleted at.
nchars
The integer with the number of characters that were deleted.
The signal is emitted after text is deleted from the entry buffer.
The "inserted-text" signal
lambda (buffer pos chars nchars)    :run-first      
buffer
The gtk:entry-buffer object.
pos
The integer with the position the text was inserted at.
chars
The string with the text that was inserted.
nchars
The integer with the number of characters that were inserted.
The signal is emitted after text is inserted into the entry buffer.
See also:
2025-1-5
Accessor gtk:entry-buffer-length (object)
Syntax:
(gtk:entry-buffer-length object) => length
Arguments:
object -- a gtk:entry-buffer object
length -- an unsigned integer for the length of the text
Details:
Accessor of the length slot of the gtk:entry-buffer class. The gtk:entry-buffer-length function retrieves the length in characters of the entry buffer. See also the gtk:entry-buffer-bytes function for the length in bytes.
See also:
2025-2-13
Accessor gtk:entry-buffer-max-length (object)
Syntax:
(gtk:entry-buffer-max-length object) => length
(setf (gtk:entry-buffer-max-length object) length)
Arguments:
object -- a gtk:entry-buffer object
length -- an integer for the maximum length of the entry buffer, or 0 for no maximum, the value passed in will be clamped to the range [0, 65536]
Details:
Accessor of the max-length slot of the gtk:entry-buffer class. The gtk:entry-buffer-max-length function returns the maximum number of characters allowed in the entry buffer, or 0 if there is no maximum. The (setf gtk:entry-buffer-max-length) function sets the maximum allowed length of the contents of the entry buffer. If the current content is longer than the given length, it will be truncated to fit.
See also:
2025-2-13
Accessor gtk:entry-buffer-text (object)
Syntax:
(gtk:entry-buffer-text object) => text
(setf (gtk:entry-buffer-text object) text)
Arguments:
object -- a gtk:entry-buffer object
text -- a string for the contents of the entry buffer
Details:
Accessor of the text slot of the gtk:entry-buffer class. The gtk:entry-buffer-text function retrieves the contents of the entry buffer. The (setf gtk:entry-buffer-text) function sets the text. This is roughly equivalent to calling the gtk:entry-buffer-delete-text and gtk:entry-buffer-insert-text functions.
See also:
2025-2-13
Function gtk:entry-buffer-new (&optional text)
Arguments:
text -- an optional string for the initial entry buffer text
Returns:
The new gtk:entry-buffer object.
Details:
Create a new entry buffer. Optionally, specify initial text to set in the entry buffer.
See also:
2025-1-5
Function gtk:entry-buffer-bytes (buffer)
Arguments:
buffer -- a gtk:entry-buffer object
Returns:
The unsigned integer with the byte length of buffer.
Details:
Retrieves the length in bytes of the entry buffer. See also the gtk:entry-buffer-length function for the length in characters.
See also:
2025-1-5
Function gtk:entry-buffer-insert-text (buffer pos text)
Arguments:
buffer -- a gtk:entry-buffer object
pos -- an integer for the position at which to insert text
text -- a string for the text to insert into the entry buffer
Returns:
The unsigned integer with the number of characters actually inserted.
Details:
Inserts text into the contents of the entry buffer, at the given position. If the pos argument or the length of the text are out of bounds, or the maximum text buffer length is exceeded, then they are coerced to sane values. Note that the position is specified in characters, not in bytes.
See also:
2025-1-5
Function gtk:entry-buffer-delete-text (buffer pos nchars)
Arguments:
buffer -- a gtk:entry-buffer object
pos -- an unsigned integer for the position at which to delete text
nchars -- an integer for the number of characters to delete
Returns:
The unsigned integer with the number of characters deleted.
Details:
Deletes a sequence of characters from the entry buffer. nchars characters are deleted starting at pos. If the nchars argument is negative, then all characters up to the end of the entry buffer are deleted.

If the pos or nchars arguments are out of bounds, then they are coerced to sane values. Note that the position is specified in characters, not bytes.
See also:
2025-2-24
Function gtk:entry-buffer-emit-deleted-text (buffer pos nchars)
Arguments:
buffer -- a gtk:entry-buffer object
pos -- an unsigned integer for the position at which text was deleted
nchars -- an integer for the number of characters deleted
Details:
Emits the "deleted-text" signal on the entry buffer. Used when subclassing the gtk:entry-buffer class.
See also:
2025-1-5
Function gtk:entry-buffer-emit-inserted-text (buffer pos text nchars)
Arguments:
buffer -- a gtk:entry-buffer object
pos -- an unsigned integer for the position at which text was inserted
text -- a string for the text that was inserted
nchars -- an integer for the number of characters inserted
Details:
Emits the "inserted-text" signal on the entry buffer. Used when subclassing the gtk:entry-buffer class.
See also:
2025-1-5

GtkText

Class gtk:text
Superclasses:
Documented Subclasses:
None
Direct Slots:
activates-default
The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget, such as the default button in a dialog, when Enter is pressed.
Default value: false
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of Pango attributes to apply to the text of the text entry. This is mainly useful to change the size or weight of the text. The start-index and end-index fields of the pango:attribute structure must refer to the text of the gtk:entry-buffer object, that is without the preedit string.
buffer
The buffer property of type gtk:entry-buffer (Read / Write)
The entry buffer which actually stores the text of the text entry.
enable-emoji-completion
The enable-emoji-completion property of type :boolean (Read / Write)
Whether to suggest Emoji replacements.
Default value: false
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model whose contents will be appended to the context menu.
im-module
The im-module property of type :string (Read / Write)
The IM (Input Method) module that should be used for the text entry. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module property.
Default value: nil
input-hints
The input-hints property of type gtk:input-hints (Read / Write)
The additional hints, beyond the input-purpose property, that allow input methods to fine-tune their behaviour.
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose of the text entry. The property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to :password or :pin is independent from setting the visibility property.
Default value: :free-from
invisible-char
The invisible-char property of type :uint (Read / Write)
The character to use when masking the content of the text entry in "password mode".
Default value: #\*
invisible-char-set
The invisible-char-set property of type :boolean (Read / Write)
Whether the invisible char has been set for the text entry.
Default value: false
max-length
The max-length property of type :int (Read / Write)
The maximum number of characters for the text entry. Zero if no maximum.
Allowed values: [0, 65535]
Default value: 0
overwrite-mode
The overwrite-mode property of type :boolean (Read / Write)
Whether text is overwritten when typing in the text entry.
Default value: false
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the text entry when it is empty and unfocused.
Default value: nil
propagate-text-width
The propagate-text-width property of type :boolean (Read / Write)
Whether the text entry should grow and shrink with the content.
Default value: false
scroll-offset
The scroll-offset property of type :int (Read)
The number of pixels the text entry scrolled off the screen to the left.
Allowed values: >= 0
Default value: 0
tabs
The tabs property of type pango:tab-array (Read / Write)
The list of tabstops to apply to the text of the text entry.
truncate-multiline
The multiline-truncate property of type :boolean (Read / Write)
When true, pasted multi-line text is truncated to the first line.
Default value: false
visibility
The visibility property of type :boolean (Read / Write)
When false displays the "invisible char" instead of the actual text (password mode).
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:text widget is a single line text entry. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible.

When using a text entry for passwords and other sensitive information, it can be put into "password mode" using the gtk:text-visibility function. In this mode, entered text is displayed using an "invisible" character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with the gtk:text-invisible-char function.

If you are looking to add icons or progress display in a text entry, look at the gtk:entry widget. There other alternatives for more specialized use cases, such as the gtk:search-entry widget.

If you need multi-line editable text, look at the gtk:text-view widget.
CSS nodes:
text[.read-only]
├── placeholder
├── undershoot.left
├── undershoot.right
├── [selection]
├── [block-cursor]
╰── [window.popup]    
The gtk:text implementation has a main node with the name text. Depending on the properties of the widget, the .read-only style class may appear. When the text entry has a selection, it adds a subnode with the name selection. When the text entry is in overwrite mode, it adds a subnode with the name block-cursor that determines how the block cursor is drawn. The CSS node for a context menu is added as a subnode below text as well.

The undershoot nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the .left and .right style classes added depending on where the indication is drawn. When touch is used and touch selection handles are shown, they are using CSS nodes with name cursor-handle. They get the .top or .bottom style class depending on where they are shown in relation to the selection. If there is just a single handle for the text cursor, it gets the .insertion-cursor style class.
Accessibility:
The gtk:text implementation uses the :none role of the gtk:accessible-role enumeration, which causes it to be skipped for accessibility. This is because the gtk:text implementation is expected to be used as a delegate for a gtk:editable implementation that will be represented to accessibility.
Signal Details:
The "activate" signal
lambda (entry)    :action      
entry
The gtk:text widget on which the signal is emitted.
The signal is emitted when the user hits the Enter key. The default bindings for this signal are all forms of the Enter key.
The "backspace" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted when the user asks for it. The default bindings for this signal are the Backspace and Shift-Backspace keys.
The "copy-clipboard" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted to copy the selection to the clipboard. The default bindings for this signal are the Ctrl-c and Ctrl-Insert keys.
The "cut-clipboard" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted to cut the selection to the clipboard. The default bindings for this signal are the Ctrl-x and Shift-Delete keys.
The "delete-from-cursor" signal
lambda (entry type count)    :action      
entry
The gtk:text widget which received the signal.
type
The granularity of the deletion, as a value of the gtk:delete-type enumeration.
count
The integer with the number of type units to delete.
The signal is a keybinding signal which gets emitted when the user initiates a text deletion. If the type is :chars, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are the Delete key for deleting a character and the Ctrl-Delete key for deleting a word.
The "insert-at-cursor" signal
lambda (entry string)    :action      
entry
The gtk:text widget which received the signal.
string
The string to insert.
The signal is a keybinding signal which gets emitted when the user initiates the insertion of a fixed string at the cursor. This signal has no default bindings.
The "insert-emoji" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted to present the Emoji chooser for the text entry. The default bindings for this signal are the Ctrl-. and Ctrl-; keys.
The "move-cursor" signal
lambda (entry step count extend)    :action      
entry
The gtk:text widget which received the signal.
step
The granularity of the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
extend
True if the move should extend the selection.
The signal is a keybinding signal which gets emitted when the user initiates a cursor movement. If the cursor is not visible in the text entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here. Arrow keys move by individual characters/lines. Ctrl-arrow key combinations move by words/paragraphs. Home/End keys move to the ends of the text entry.
The "paste-clipboard" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted to paste the contents of the clipboard into the text entry. The default bindings for this signal are the Ctrl-v and Shift-Insert keys.
The "preedit-changed" signal
lambda (entry preedit)    :action      
entry
The gtk:text widget which received the signal.
preedit
The current preedit string.
If an input method is used, the typed text will not immediately be committed to the entry buffer. So if you are interested in the text, connect to this signal.
The "toggle-overwrite" signal
lambda (entry)    :action      
entry
The gtk:text widget which received the signal.
The signal is a keybinding signal which gets emitted to toggle the overwrite mode of the text entry. The default bindings for this signal is the Insert key.
Action Details:
menu.popup}{Opens the context menu.} @entry[text.redo
Redoes the last change to the contents.
text.undo
Undoes the last change to the contents.
misc.toggle-visibility
Toggles the “visibility” property.
misc.insert-emoji
Opens the Emoji chooser.
selection.select-all
Selects all of the widgets content.
selection.delete
Deletes the current selection.
clipboard.paste
Inserts the contents of the clipboard into the widget.
clipboard.copy
Copies the contents to the clipboard.
clipboard.cut
Copies the contents to the clipboard and deletes it from the widget.
See also:
2024-11-15
Accessor gtk:text-activates-default (object)
Syntax:
(gtk:text-activates-default object) => setting
(setf (gtk:text-activates-default object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether to activate the default widget, when Enter is pressed
Details:
Accessor of the activates-default slot of the gtk:text class. If the activates-default property is true, pressing Enter in the text entry will activate the default widget for the window containing the text entry. This usually means that the dialog containing the text entry will be closed, since the default widget is usually one of the dialog buttons.
See also:
2024-5-22
Accessor gtk:text-attributes (object)
Syntax:
(gtk:text-attributes object) => attributes
(setf (gtk:text-attributes object) attributes)
Arguments:
object -- a gtk:text widget
attributes -- a pango:attr-list instance
Details:
Accessor of the attributes slot of the gtk:text class. The gtk:text-attributes function gets the attribute list that was set on the text entry, if any. The (setf gtk:text-attributes) function sets an attribute list. The attributes in the list are applied to the text.
See also:
2024-5-17
Accessor gtk:text-buffer (object)
Syntax:
(gtk:text-buffer object) => buffer
(setf (gtk:text-buffer object) buffer)
Arguments:
object -- a gtk:text widget
buffer -- a gtk:entry-buffer object
Details:
Accessor of the buffer slot of the gtk:text class. The gtk:text-buffer function gets the gtk:entry-buffer object which holds the text for the text entry. The (setf gtk:text-buffer) function sets the gtk:entry-buffer object.
See also:
2024-5-17
Accessor gtk:text-enable-emoji-completion (object)
Syntax:
(gtk:text-enable-emoji-completion object) => setting
(setf (gtk:text-enable-emoji-completion object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether to enable Emoji completion
Details:
Accessor of the enable-emoji-completion slot of the gtk:text class. The gtk:text-enable-emoji-completion function returns whether Emoji completion is enabled for the text entry. The (setf gtk:text-enable-emoji-completion) function sets whether Emoji completion is enabled. If it is, typing ':', followed by a recognized keyword, will pop up a window with suggested Emojis matching the keyword.
See also:
2024-5-17
Accessor gtk:text-extra-menu (object)
Syntax:
(gtk:text-extra-menu object) => menu
(setf (gtk:text-extra-menu object) menu)
Arguments:
object -- a gtk:text widget
menu -- a g:menu-model object
Details:
Accessor of the extra-menu slot of the gtk:text class. The gtk:text-extra-menu function gets the menu model. The (setf gtk:text-extra-menu) function sets a menu model to add when constructing the context menu for the text entry.
See also:
2024-5-17
Accessor gtk:text-im-module (object)
Syntax:
(gtk:text-im-module object) => module
(setf (gtk:text-im-module object) module)
Arguments:
object -- a gtk:text widget
module -- a string with the IM (input method) module
Details:
Accessor of the im-module slot of the gtk:text class. The IM (Input Method) module that should be used for the text entry. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module property.
See also:
2024-5-17
Accessor gtk:text-input-hints (object)
Syntax:
(gtk:text-input-hints object) => hints
(setf (gtk:text-input-hints object) hints)
Arguments:
object -- a gtk:text widget
hints -- a gtk:input-hints value
Details:
Accessor of the input-hints slot of the gtk:text class. The gtk:text-input-hints function gets the value of the input-hints property, which allows input methods to fine-tune their behaviour. The (setf gtk:text-input-hints) function sets the property.
See also:
2024-5-23
Accessor gtk:text-input-purpose (object)
Syntax:
(gtk:text-input-purpose object) => purpose
(setf (gtk:text-input-purpose object) purpose)
Arguments:
object -- a gtk:text widget
purpose -- a gtk:input-purpose value
Details:
Accessor of the input-purpose slot of the gtk:text class. The gtk:text-input-purpose function gets the value of the input-purpose property, which can be used by on-screen keyboards and other input methods to adjust their behaviour. The (setf gtk:text-input-purpose) function sets the property.
See also:
2024-5-17
Accessor gtk:text-invisible-char (object)
Syntax:
(gtk:text-invisible-char object) => char
(setf (gtk:text-invisible-char object) char)
Arguments:
object -- a gtk:text widget
char -- an unsigned integer with an Unicode character
Details:
Accessor of the invisible-char slot of the gtk:text class. The gtk:text-invisible-char function retrieves the character displayed in place of the real characters for entries with visibility set to false. Note that GTK does not compute this value unless it needs it, so the value returned by this function is not very useful unless it has been explicitly set. The (setf gtk:text-invisible-char) function sets the character.

By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all. There will be no text on the screen as they type.
See also:
2024-5-17
Accessor gtk:text-invisible-char-set (object)
Syntax:
(gtk:text-invisible-char-set object) => setting
(setf (gtk:text-invisible-char-set object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether the invisible char has been set
Details:
Accessor of the invisible-char-set slot of the gtk:text class. Whether the invisible char has been set for the text entry.
See also:
2024-5-17
Accessor gtk:text-max-length (object)
Syntax:
(gtk:text-max-length object) => length
(setf (gtk:text-max-length object) length)
Arguments:
object -- a gtk:text widget
length -- an integer with the maximum length of the text entry or 0 if there is no maximum
Details:
Accessor of the max-length slot of the gtk:text class. The gtk:text-max-length function retrieves the maximum allowed length of the text in the text entry. This is equivalent to getting the gtk:entry-buffer object for the text entry and calling the gtk:entry-buffer-max-length function on it.

The (setf gtk:text-max-length) function sets the maximum allowed length. If the current contents are longer than the given length, then they will be truncated to fit. This is equivalent to getting the gtk:entry-buffer object for the text entry and calling the (setf gtk:entry-buffer-max-length) function on it.
See also:
2024-5-17
Accessor gtk:text-overwrite-mode (object)
Syntax:
(gtk:text-overwrite-mode object) => setting
(setf (gtk:text-overwrite-mode object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether the text is overwritten when typing
Details:
Accessor of the overwrite-mode slot of the gtk:text class. The gtk:text-overwrite-mode function gets the value of the property. The (setf gtk:text-overwrite-mode) function sets whether the text is overwritten when typing in the text entry.
See also:
2024-5-23
Accessor gtk:text-placeholder-text (object)
Syntax:
(gtk:text-placeholder-text object) => text
(setf (gtk:text-placeholder-text object) text)
Arguments:
object -- a gtk:text widget
text -- a string to be displayed when the text entry is empty and unfocused, or nil
Details:
Accessor of the placeholder-text slot of the gtk:text class. The gtk:text-placeholder-text function retrieves the text that will be displayed when the text entry is empty and unfocused. The (setf gtk:text-placeholder-text) function sets text to be displayed. This can be used to give a visual hint for the expected contents of the text entry.
See also:
2024-5-17
Accessor gtk:text-propagate-text-width (object)
Syntax:
(gtk:text-propagate-text-width object) => setting
(setf (gtk:text-propagate-text-width object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether the text entry should grow and shrink with the content
Details:
Accessor of the propagate-text-width slot of the gtk:text class. The gtk:text-propagate-text-width function returns whether the text entry will grow and shrink with the content. The (setf gtk:text-propagate-text-width) function sets the property.
See also:
2024-5-17
Accessor gtk:text-scroll-offset (object)
Syntax:
(gtk:text-scroll-offset object) => offset
(setf (gtk:text-scroll-offset object) offset)
Arguments:
object -- a gtk:text widget
offset -- an integer with the number of pixels the text entry scrolled off the screen
Details:
Accessor of the scroll-offset slot of the gtk:text class. The number of pixels the text entry scrolled off the screen to the left.
See also:
2024-5-17
Accessor gtk:text-tabs (object)
Syntax:
(gtk:text-tabs object) => tabs
(setf (gtk:text-tabs object) tabs)
Arguments:
object -- a gtk:text widget
tabs -- a pango:tab-array instance with the tabstops
Details:
Accessor of the tabs slot of the gtk:text class. The gtk:text-tabs function gets the tabstops that were set on the text entry, if any. The (setf gtk:text-tabs) function sets the tabstopps. The tabstops are applied to the text in the text entry.
See also:
2024-5-17
Accessor gtk:text-truncate-multiline (object)
Syntax:
(gtk:text-truncate-multiline object) => setting
(setf (gtk:text-truncate-multiline object) setting)
Arguments:
object -- a gtk:text widget
setting -- a boolean whether the text entry will truncate multi-line text
Details:
Accessor of the truncate-multiline slot of the gtk:text class. The gtk:text-truncate-multiline function returns whether the text entry will truncate multi-line text that is pasted into the widget. The (setf gtk:text-truncate-multiline) function sets the property.
See also:
2024-5-17
Accessor gtk:text-visibility (object)
Syntax:
(gtk:text-visibility object) => visible
(setf (gtk:text-visibility object) visible)
Arguments:
object -- a gtk:text widget
visible -- a boolean whether the text is visible
Details:
Accessor of the visibility slot of the gtk:text class. The gtk:text-visibility function retrieves whether the text in the text entry is visible. The (setf gtk:text-visibility) function sets whether the contents of the text entry are visible or not. When visibility is set to false, characters are displayed as the invisible char, and will also appear that way when the text in the text entry is copied to the clipboard.

By default, GTK picks the best invisible character available in the current font, but it can be changed with the gtk:text-invisible-char function.

Note that you probably want to set the input-purpose property to the :password or :pin value to inform input methods about the purpose of the text entry, in addition to setting the visibility property to false.
See also:
2024-5-17
Function gtk:text-new ()
Returns:
The new gtk:text widget.
Details:
Creates a new text widget.
See also:
2024-5-17
Function gtk:text-new-with-buffer (buffer)
Arguments:
buffer -- a gtk:entry-buffer object
Returns:
The new gtk:text widget.
Details:
Creates a new text widget with the specified entry buffer.
See also:
2024-5-17
Function gtk:text-unset-invisible-char (entry)
Arguments:
entry -- a gtk:text widget
Details:
Unsets the invisible char previously set with the gtk:text-invisible-char function, so that the default invisible char is used again.
See also:
2024-5-17
Function gtk:text-text-length (entry)
Arguments:
entry -- a gtk:text widget
Returns:
The unsigned integer with the current number of characters in the gtk:text widget.
Details:
Retrieves the current length of the text in entry. This is equivalent to getting the gtk:entry-buffer object of the text widget and calling the gtk:entry-buffer-length function on it.
See also:
2024-5-17
Function gtk:text-grab-focus-without-selecting (entry)
Arguments:
entry -- a gtk:text widget
Returns:
True if focus is inside entry.
Details:
Causes the text widget to have keyboard focus. It behaves like the gtk:widget-grab-focus function, except that it does not select the contents of text entry. You only want to call this on some special entries which the user usually does not want to replace all text in, such as search-as-you-type entries.
See also:
#2024-11-15
Function gtk:text-compute-cursor-extents (entry position strong weak)
Arguments:
entry -- a gtk:text widget
position -- an integer with the character position
strong -- a graphene:rect-t instance to store the strong cursor position, the argument can be nil
weak -- a graphene:rect-t instance to store the weak cursor position, the argument can be nil
Details:
Determine the positions of the strong and weak cursors if the insertion point in the layout is at position. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction are inserted. The rectangle positions are in widget coordinates.

Since 4.4
Examples:
Use the graphene:with-rect or graphene:with-rects macro to create the rectangles passed to the function.
(graphene:with-rects (strong weak)
  (gtk:text-compute-cursor-extents text pos strong weak)
  ... )    
See also:
2024-5-17

GtkEntry

GEnum gtk:entry-icon-position
Declaration:
(gobject:define-genum "GtkEntryIconPosition" entry-icon-position
  (:export t
   :type-initializer "gtk_entry_icon_position_get_type")
  (:primary 0)
  (:secondary 1))  
Values:
:primary
At the beginning of the text entry, depending on the text direction.
:secondary
At the end of the text entry, depending on the text direction.
Details:
Specifies the side of the text entry at which an icon is placed.
See also:
2023-9-16
Class gtk:entry
Superclasses:
Documented Subclasses:
None
Direct Slots:
activates-default
The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget, such as the default button in a dialog, when the Enter key is pressed.
Default value: false
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of Pango attributes to apply to the text of the text entry. This is mainly useful to change the size or weight of the text. The start-index and end-index fields of the pango:attribute structure must refer to the text of the gtk:entry-buffer object, for example, without the preedit string.
buffer
The buffer property of type gtk:entry-buffer (Read / Write / Construct)
The entry buffer which actually stores the text for the text entry.
completion
The completion property of type gtk:entry-completion (Read / Write)
The auxiliary completion object to use with the entry. Deprecated 4.10
enable-emoji-completion
The enable-emoji-completion property of type :boolean (Read / Write)
Whether to suggest Emoji replacements.
Default value: false
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model whose contents will be appended to the context menu.
has-frame
The has-frame property of type :boolean (Read / Write)
False removes outside bevel from the text entry.
Default value: true
im-module
The im-module property of type :string (Read / Write)
The IM (Input Method) module that should be used for the text entry. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module setting.
Default value: nil
input-hints
The input-hints property of type gtk:input-hints (Read / Write)
Additional hints, beyond the input-purpose property, that allow input methods to fine-tune their behaviour.
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose of the text entry. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to the :password or :pin values is independent from setting the visibility property.
Default value: :free-form
invisible-char
The invisible-char property of type :uint (Read / Write)
The invisible character is used when masking the text entry contents in "password mode".
Default value: (char-code #*)
invisible-char-set
The invisible-char-set property of type :boolean (Read / Write)
Whether the invisible char has been set for the text entry.
Default value: false
max-length
The max-length property of type :int (Read / Write)
The maximum number of characters for the text entry. Zero if no maximum.
Allowed values: [0,65535]
Default value: 0
overwrite-mode
The overwrite-mode property of type :boolean (Read / Write)
Whether text is overwritten when typing in the text entry.
Default value: false
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the text entry when it is empty and unfocused.
Default value: nil
primary-icon-activatable
The primary-icon-activatable property of type :boolean (Read / Write)
Whether the primary icon is activatable. GTK emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
Default value: true
primary-icon-gicon
The primary-icon-gicon property of type g:icon (Read / Write)
The icon to use as the primary icon for the text entry.
primary-icon-name
The primary-icon-name property of type :string (Read / Write)
The icon name from the current icon theme to use as the primary icon for the text entry.
Default value: nil
primary-icon-paintable
The primary-icon-paintable property of type gdk:paintable (Read / Write)
The paintable to use as the primary icon for the text entry.
primary-icon-sensitive
The primary-icon-sensitive property of type :boolean (Read / Write)
Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the "icon-press" and "icon-release" signals and does not allow drag and drop from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
Default value: true
primary-icon-storage-type
The primary-icon-storage-type property of type gtk:image-type (Read)
The representation which is used for the primary icon of the text entry.
Default value: :empty
primary-icon-tooltip-markup
The primary-icon-tooltip-markup property of type :string (Read / Write)
The contents of the tooltip on the primary icon, which is marked up with the Pango text markup language. Also see the gtk:entry-icon-tooltip-markup function.
Default value: nil
primary-icon-tooltip-text
The primary-icon-tooltip-text property of type :string (Read / Write)
The contents of the tooltip on the primary icon.
Default value: nil
progress-fraction
The progress-fraction property of type :double (Read / Write)
The current fraction of the task that is been completed.
Allowed values: [0,1]
Default value: 0
progress-pulse-step
The progress-pulse-step property of type :double (Read / Write)
The fraction of total text entry width to move the progress bouncing block for each call to the gtk:entry-progress-pulse function.
Allowed values: [0,1]
Default value: 0.0
scroll-offset
The scroll-offset property of type :int (Read)
The number of pixels of the text entry scrolled off the screen to the left.
Allowed values: >= 0
Default value: 0
secondary-icon-activatable
The secondary-icon-activatable property of type :boolean (Read / Write)
Whether the secondary icon is activatable. GTK emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
Default value: true
secondary-icon-gicon
The secondary-icon-gicon property of type g:icon (Read / Write)
The icon to use as the secondary icon for the text entry.
secondary-icon-name
The secondary-icon-name property of type :string (Read / Write)
The icon name from the current icon theme to use as the secondary icon for the text entry.
Default value: nil
secondary-icon-paintable
The secondary-icon-paintable property of type gdk:paintable (Read / Write)
The paintable to use as the secondary icon for the text entry.
secondary-icon-sensitive
The secondary-icon-sensitive property of type :boolean (Read / Write)
Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the "icon-press" and "icon-release" signals and does not allow drag and drop from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
Default value: true
secondary-icon-storage-type
The secondary-icon-storage-type property of type gtk:image-type (Read)
The representation which is used for the secondary icon of the text entry.
Default value: :empty
secondary-icon-tooltip-markup
The secondary-icon-tooltip-markup property of type :string (Read / Write)
The contents of the tooltip on the secondary icon, which is marked up with the Pango text markup language. Also see the gtk:entry-icon-tooltip-markup function.
Default value: nil
secondary-icon-tooltip-text
The secondary-icon-tooltip-text property of type :string (Read / Write)
The contents of the tooltip on the secondary icon.
Default value: nil
show-emoji-icon
The show-emoji-icon property of type :boolean (Read / Write)
Whether to show an icon for Emoji.
Default value: false
tabs
The tabs property of type pango:tab-array (Read / Write)
The list of tabstop locations to apply to the text of the text entry.
text-length
The text-length property of type :uint (Read)
The length of the text in the text entry.
Allowed values: <= 65535
Default value: 0
truncate-multiline
The truncate-multiline property of type :boolean (Read / Write)
When true, pasted multi-line text is truncated to the first line.
Default value: false
visibility
The visibility property of type :boolean (Read / Write)
False displays the "invisible char" instead of the actual text (password mode).
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:entry widget is a single line text entry. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible.

Figure: GtkEntry

When using a text entry for passwords and other sensitive information, it can be put into "password mode" using the gtk:entry-visibility function. In this mode, entered text is displayed using an 'invisible' character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with the gtk:entry-invisible-char function.

The gtk:entry widget has the ability to display progress or activity information behind the text. To make a text entry display such information, use the gtk:entry-progress-fraction or gtk:entry-progress-pulse-step functions.

Additionally, the gtk:entry widget can show icons at either side of the text entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use the gtk:entry-set-icon-from-gicon function or one of the various other functions that set an icon from an icon name or a paintable. To trigger an action when the user clicks an icon, connect to the "icon-press" signal. To allow DND operations from an icon, use the gtk:entry-set-icon-drag-source function. To set a tooltip on an icon, use the gtk:entry-icon-tooltip-text function or the corresponding function for markup.

Note that functionality or information that is only available by clicking on an icon in an text entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that such functionality is also available by other means, such as the context menu of the text entry.
CSS nodes:
entry[.flat][.warning][.error]
├── text[.readonly]
├── image.left
├── image.right
╰── [progress[.pulse]]    
The gtk:entry implementation has a main node with the name entry. Depending on the properties of the text entry, the .read-only and .flat style classes may appear. The .warning and .error style classes may also be used with entries.

When the text entry shows icons, it adds subnodes with the name image and the .left or .right style class, depending on where the icon appears.

When the text entry shows progress, it adds a subnode with the name progress. The node has the .pulse style class when the shown progress is pulsing.

For all the subnodes added to the text node in various situations, see the gtk:text widget.
GtkEntry as GtkBuildable:
The gtk:entry implementation of the gtk:buildable interface supports a custom <attributes> element, which supports any number of <attribute> elements. The <attribute> element has attributes named "name", "value", "start" and "end" and allows you to specify pango:attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:
<object class="GtkEntry">
  <attributes>
    <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
    <attribute name="background" value="red" start="5" end="10"/>
  </attributes>
</object>    
The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead.
Accessibility:
The gtk:entry implementation uses the :text-box role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (entry)    :action      
entry
The gtk:entry widget on which the signal is emitted.
A keybinding signal which gets emitted when the user activates the text entry. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control activation programmatically. The default bindings for this signal are all forms of the Enter key.
The "icon-press" signal
lambda (entry pos)    :run-last      
entry
The gtk:entry widget on which the signal is emitted.
pos
The position of the clicked icon as a gtk:entry-icon-position value.
The signal is emitted when an activatable icon is clicked.
The "icon-release" signal
lambda (entry pos)    :run-last      
entry
The gtk:entry widget on which the signal is emitted.
pos
The position of the clicked icon as a gtk:entry-icon-position value.
The signal is emitted on the button release from a mouse click over an activatable icon.
See also:
2024-11-26
Accessor gtk:entry-activates-default (object)
Syntax:
(gtk:entry-activates-default object) => setting
(setf (gtk:entry-activates-default object) setting)
Arguments:
object -- a gtk:entry widget
setting -- true to activate the default widget of the window on Enter keypress
Details:
Accessor of the activates-default slot of the gtk:entry class. The gtk:entry-activates-default function retrieves whether to activate the default widget, when the Enter key is pressed.

If the setting argument is true, pressing the Enter key in the text entry will activate the default widget for the window containing the text entry. This usually means that the dialog containing the text entry will be closed, since the default widget is usually one of the dialog buttons.
See also:
2024-5-22
Accessor gtk:entry-attributes (object)
Syntax:
(gtk:entry-attributes object) => attrs
(setf (gtk:entry-attributes object) attrs)
Arguments:
object -- a gtk:entry widget
attrs -- a pango:attr-list instance
Details:
Accessor of the attributes slot of the gtk:entry class. The gtk:entry-attributes function gets the attribute list, if any. The (setf gtk:entry-attributes) function sets a attributes list. The attributes in the list are applied to the text of the text entry.
See also:
2024-5-22
Accessor gtk:entry-buffer (object)
Syntax:
(gtk:entry-buffer object) => buffer
(setf (gtk:entry-buffer object) buffer)
Arguments:
object -- a gtk:entry widget
buffer -- a gtk:entry-buffer object
Details:
Accessor of the buffer slot of the gtk:entry class. The gtk:entry-buffer function gets the entry buffer which holds the text for the text entry. The (setf gtk:entry-buffer) function sets the entry buffer.
See also:
2024-5-22
Accessor gtk:entry-completion (object)
Syntax:
(gtk:entry-completion object) => completion
(setf (gtk:entry-completion object) completion)
Arguments:
object -- a gtk:entry widget
completion -- a gtk:entry-completion object or nil
Details:
Accessor of the completion slot of the gtk:entry class. The gtk:entry-completion function returns the auxiliary completion object currently in use by the text entry. The (setf gtk:entry-completion) function sets the auxiliary completion object.

All further configuration of the completion mechanism is done on completion using the gtk:entry-completion API. Completion is disabled if the completion property is set to nil.
Warning:
This function is deprectated since 4.10. The gtk:entry-completion implementation will be removed in GTK 5.
See also:
2024-5-22
Accessor gtk:entry-enable-emoji-completion (object)
Syntax:
(gtk:entry-enable-emoji-completion object) => enable
(setf (gtk:entry-enable-emoji-completion object) enable)
Arguments:
object -- a gtk:entry widget
enable -- a boolean whether to suggest Emoji replacements
Details:
Accessor of the enable-emoji-completion slot of the gtk:entry class. Whether to suggest Emoji replacements.
See also:
2024-5-22
Accessor gtk:entry-extra-menu (object)
Syntax:
(gtk:entry-extra-menu object) => menu
(setf (gtk:entry-extra-menu object) menu)
Arguments:
object -- a gtk:entry widget
menu -- a g:menu-model object
Details:
Accessor of the extra-menu slot of the gtk:entry class. The gtk:entry-extra-menu function gets the menu model. The (setf gtk:entry-extra-menu) function sets a menu model to add when constructing the context menu for the text entry.
See also:
2024-5-22
Accessor gtk:entry-has-frame (object)
Syntax:
(gtk:entry-has-frame object) => setting
(setf (gtk:entry-has-frame object) setting)
Arguments:
object -- a gtk:entry widget
setting -- a boolean whether to remove bevel from the text entry field
Details:
Accessor of the has-frame slot of the gtk:entry class. The gtk:entry-has-frame function returns whether the text entry has a beveled frame. The (setf gtk:entry-has-frame) function sets whether the the entry has a beveled frame around it.
See also:
2024-5-22
Accessor gtk:entry-im-module (object)
Syntax:
(gtk:entry-im-module object) => setting
(setf (gtk:entry-im-module object) setting)
Arguments:
object -- a gtk:entry widget
setting -- a string with the IM (Input Method] module that should be used for the text entry
Details:
Accessor of the im-module slot of the gtk:entry class. The IM (Input Method) module that should be used for the text entry. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the im-module documentation.
See also:
2024-11-26
Accessor gtk:entry-input-hints (object)
Syntax:
(gtk:entry-input-hints object) => hints
(setf (gtk:entry-input-hints object) hints)
Arguments:
object -- a gtk:entry widget
hints -- a value of the gtk:input-hints enumeration
Details:
Accessor of the input-hints slot of the gtk:entry class. The gtk:entry-input-hints function gets the property. The (setf gtk:entry-input-hints) function sets the property, which allows input methods to fine-tune their behaviour.
See also:
2024-11-26
Accessor gtk:entry-input-purpose (object)
Syntax:
(gtk:entry-input-purpose object) => purpose
(setf (gtk:entry-input-purpose object) purpose)
Arguments:
object -- a gtk:entry widget
purpose -- a value of the gtk:input-purpose enumeration
Details:
Accessor of the input-purpose slot of the gtk:entry class. The gtk:entry-input-purpose function gets the value of the property. The (setf gtk:entry-input-purpose) function sets the property which can be used by on-screen keyboards and other input methods to adjust their behaviour.
See also:
2024-5-22
Accessor gtk:entry-invisible-char (object)
Syntax:
(gtk:entry-invisible-char object) => char
(setf (gtk:entry-invisble-char object) char)
Arguments:
object -- a gtk:entry widget
char -- an unsigned integer with a Unicode char code
Details:
Accessor of the invisible-char slot of the gtk:entry class. The gtk:entry-invisible-char function retrieves the character displayed in place of the real characters for entries with visibility set to false. The (setf gtk:entry-invisible-char) function sets the character to use in place of the actual text.

For example, this is the character used in "password mode" to show the user how many characters have been typed. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all. There will be no text on the screen as they type.
See also:
2024-11-26
Accessor gtk:entry-invisible-char-set (object)
Syntax:
(gtk:entry-invisible-char-set object) => setting
(setf (gtk:entry-invisible-char-set object) setting)
Arguments:
object -- a gtk:entry widget
setting -- a boolean whether the invisible char has been set for the text entry
Details:
Accessor of the invisible-char-set slot of the gtk:entry class. Whether the invisible char has been set for the text entry.
See also:
2024-5-22
Accessor gtk:entry-max-length (object)
Syntax:
(gtk:entry-max-length object) => max
(setf (gtk:entry-max-length object) max)
Arguments:
object -- a gtk:entry widget
max -- an integer with the maximum length of the text entry, or 0 for no maximum, the value passed in will be clamped to the range [0, 65536]
Details:
Accessor of the max-length slot of the gtk:entry class. The gtk:entry-max-length function retrieves the maximum allowed length of the text in the text entry, or 0 if there is no maximum. The (setf gtk:entry-max-length) function sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit.
Notes:
This function is equivalent to
(gtk:entry-buffer-max-length (gtk:entry-buffer object))    
and
(setf (gtk:entry-buffer-max-length (gtk:entry-buffer object)) max)    
See also:
2024-5-22
Accessor gtk:entry-overwrite-mode (object)
Syntax:
(gtk:entry-overwrite-mode object) => overwrite
(setf (gtk:entry-overwrite-mode object) overwrite)
Arguments:
object -- a gtk:entry widget
overwrite -- a boolean whether the text is overwritten when typing
Details:
Accessor of the overwrite-mode slot of the gtk:entry class. The gtk:entry-overwrite-mode function returns whether the text is overwritten when typing in the text entry. The (setf gtk:entry-overwrite-mode) function sets whether the text is overwritten when typing.
See also:
2024-5-22
Accessor gtk:entry-placeholder-text (object)
Syntax:
(gtk:entry-placeholder-text object) => text
(setf (gtk:entry-placeholder-text object) text)
Arguments:
object -- a gtk:entry widget
text -- a string to be displayed when the text entry is empty and unfocused, or nil
Details:
Accessor of the placeholder-text slot of the gtk:entry class. The gtk:entry-placeholder-text function retrieves the text that will be displayed when the text entry is empty and unfocused. The (setf gtk:entry-placeholder-text) function sets the text. This can be used to give a visual hint of the expected contents of the text entry.

Note that since the placeholder text gets removed when the text entry received focus, using this feature is a bit problematic if the text entry is given the initial focus in a window. Sometimes this can be worked around by delaying the initial focus setting until the first key event arrives.
See also:
2024-11-26
Accessor gtk:entry-primary-icon-activatable (object)
Syntax:
(gtk:entry-primary-icon-activatable object) => activatable
(setf (gtk:entry-primary-icon-activatable object) activatable)
Arguments:
object -- a gtk:entry widget
activatable -- a boolean whether the primary icon is activatable
Details:
Accessor of the primary-icon-activatable slot of the gtk:entry class. Whether the primary icon is activatable. GTK emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
See also:
2024-5-22
Accessor gtk:entry-primary-icon-gicon (object)
Syntax:
(gtk:entry-primary-icon-gicon object) => icon
(setf (gtk:entry-primary-icon-gicon object) icon)
Arguments:
object -- a gtk:entry widget
icon -- a g:icon object
Details:
Accessor of the primary-icon-gicon slot of the gtk:entry class. The icon to use as the primary icon for the text entry.
See also:
2024-11-26
Accessor gtk:entry-primary-icon-name (object)
Syntax:
(gtk:entry-primary-icon-name object) => name
(setf (gtk:entry-primary-icon-name object) name)
Arguments:
object -- a gtk:entry widget
name -- a string with the icon name
Details:
Accessor of the primary-icon-name slot of the gtk:entry class. The icon name from the current icon theme to use as the primary icon for the text entry.
See also:
2023-4-7
Accessor gtk:entry-primary-icon-paintable (object)
Syntax:
(gtk:entry-primary-icon-paintable object) => paintable
(setf (gtk:entry-primary-icon-paintable object) paintable)
Arguments:
object -- a gtk:entry widget
paintable -- a gdk:paintable object
Details:
Accessor of the primary-icon-paintable slot of the gtk:entry class. A paintable to use as the primary icon for the text entry.
See also:
2024-5-22
Accessor gtk:entry-primary-icon-sensitive (object)
Syntax:
(gtk:entry-primary-icon-sensitive object) => sensitive
(setf (gtk:entry-primary-icon-sensitive object) sensitive)
Arguments:
object -- a gtk:entry widget
sensitive -- a boolean whether the primary icon is sensitive
Details:
Accessor of the primary-icon-sensitive slot of the gtk:entry class. Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the "icon-press" and "icon-release" signals and does not allow drag and drop from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
See also:
2024-5-22
Accessor gtk:entry-primary-icon-storage-type (object)
Syntax:
(gtk:entry-primary-icon-storage-type object) => type
(setf (gtk:entry-primary-icon-storage-type object) type)
Arguments:
object -- a gtk:entry widget
type -- a value of the gtk:image-type enumeration
Details:
Accessor of the primary-icon-storage-type slot of the gtk:entry class. The representation which is used for the primary icon of the text entry.
See also:
2024-5-22
Accessor gtk:entry-primary-icon-tooltip-markup (object)
Syntax:
(gtk:entry-primary-icon-tooltip-markup object) => markup
(setf (gtk:entry-primary-icon-tooltip-markup object) markup)
Arguments:
object -- a gtk:entry widget
markup -- a string with the contents of the tooltip
Details:
Accessor of the primary-icon-tooltip-markup slot of the gtk:entry class. The contents of the tooltip on the primary icon, which is marked up with the Pango text markup language. Also see the gtk:entry-icon-tooltip-markup function.
See also:
2024-5-22
Accessor gtk:entry-primary-icon-tooltip-text (object)
Syntax:
(gtk:entry-primary-icon-tooltip-text object) => text
(setf (gtk:entry-primary-icon-tooltip-text object) text)
Arguments:
object -- a gtk:entry widget
text -- a string with the contents of the tooltip
Details:
Accessor of the primary-icon-tooltip-text slot of the gtk:entry class. The contents of the tooltip on the primary icon. Also see the gtk:entry-icon-tooltip-text function.
See also:
2024-4-7
Accessor gtk:entry-progress-fraction (object)
Syntax:
(gtk:entry-progress-fraction object) => fraction
(setf (gtk:entry-progress-fraction object) fraction)
Arguments:
object -- a gtk:entry widget
fraction -- a double float with the fraction of the task that is been completed
Details:
Accessor of the progress-fraction slot of the gtk:entry class. The gtk:entry-progress-fraction function returns the current fraction that is been completed. The (setf gtk:entry-progress-fraction) function causes the text entry progress indicator to "fill in" the given fraction of the progress bar. The fraction should be between 0.0 and 1.0, inclusive.
See also:
2024-5-22
Accessor gtk:entry-progress-pulse-step (object)
Syntax:
(gtk:entry-progress-pulse-step object) => step
(setf (gtk:entry-progress-pulse-step object) step)
Arguments:
object -- a gtk:entry widget
step -- a double float with the fraction between 0.0 and 1.0
Details:
Accessor of the progress-pulse-step slot of the gtk:entry class. The gtk:entry-progress-pulse-step function retrieves the pulse step as a fraction from 0.0 to 1.0. The (setf gtk:entry-progress-pulse-step) function sets the fraction of total text entry width to move the progress bouncing block for each call to the gtk:entry-progress-pulse function.
See also:
2024-5-22
Accessor gtk:entry-scroll-offset (object)
Syntax:
(gtk:entry-scroll-offset object) => offset
(setf (gtk:entry-scroll-offset object) offset)
Arguments:
object -- a gtk:entry widget
offset -- an integer with the number of pixels the text entry is scrolled off
Details:
Accessor of the scroll-offset slot of the gtk:entry class. The number of pixels the text entry is scrolled off the screen to the left.
See also:
2024-11-26
Accessor gtk:entry-secondary-icon-activatable (object)
Syntax:
(gtk:entry-secondary-icon-activatable object) => activatable
(setf (gtk:entry-secondary-icon-activatable object) activatable)
Arguments:
object -- a gtk:entry widget
activatable -- a boolean whether the secondary icon is activatable
Details:
Accessor of the secondary-icon-activatable slot of the gtk:entry class. Whether the secondary icon is activatable. GTK emits the "icon-press" and "icon-release" signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes.
See also:
2024-5-22
Accessor gtk:entry-secondary-icon-gicon (object)
Syntax:
(gtk:entry-secondary-icon-gicon object) => icon
(setf (gtk:entry-secondary-icon-gicon object) icon)
Arguments:
object -- a gtk:entry widget
icon -- a g:icon object
Details:
Accessor of the secondary-icon-gicon slot of the gtk:entry class. The icon to use as the secondary icon for the text entry.
See also:
2024-11-26
Accessor gtk:entry-secondary-icon-name (object)
Syntax:
(gtk:entry-secondary-icon-name object) => name
(setf (gtk:entry-secondary-icon-name object) name)
Arguments:
object -- a gtk:entry widget
name -- a string with the icon name
Details:
Accessor of the secondary-icon-name slot of the gtk:entry class. The icon name from the current icon theme to use as the secondary icon for the text entry.
See also:
2024-4-7
Accessor gtk:entry-secondary-icon-paintable (object)
Syntax:
(gtk:entry-secondary-icon-paintable object) => paintable
(setf (gtk:entry-secondary-icon-paintable object) paintable)
Arguments:
object -- a gtk:entry widget
paintable -- a gdk:paintable object
Details:
Accessor of the secondary-icon-paintable slot of the gtk:entry class. The paintable to use as the secondary icon for the text entry.
See also:
2024-5-22
Accessor gtk:entry-secondary-icon-sensitive (object)
Syntax:
(gtk:entry-secondary-icon-sensitive object) => sensitive
(setf (gtk:entry-secondary-icon-sensitive object) sensitive)
Arguments:
object -- a gtk:entry widget
sensitive -- a boolean whether the icon is sensitive
Details:
Accessor of the secondary-icon-sensitive slot of the gtk:entry class. Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the "icon-press" and "icon-release" signals and does not allow drag and drop from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available.
See also:
2024-5-22
Accessor gtk:entry-secondary-icon-storage-type (object)
Syntax:
(gtk:entry-secondary-icon-storage-type object) => type
(setf (gtk:entry-secondary-icon-storage-type object) type)
Arguments:
object -- a gtk:entry widget
type -- a value of the gtk:image-type enumeration
Details:
Accessor of the secondary-icon-storage-type slot of the gtk:entry class. The representation which is used for the secondary icon of the text entry.
See also:
2024-5-22
Accessor gtk:entry-secondary-icon-tooltip-markup (object)
Syntax:
(gtk:entry-secondary-icon-tooltip-markup object) => markup
(setf (gtk:entry-secondary-icon-tooltip-markup object) markup)
Arguments:
object -- a gtk:entry widget
markup -- a string with the contents of the tooltip
Details:
Accessor of the secondary-icon-tooltip-markup slot of the gtk:entry class. The contents of the tooltip on the secondary icon, which is marked up with the Pango text markup language. Also see the gtk:entry-icon-tooltip-markup function.
See also:
2024-5-22
Accessor gtk:entry-secondary-icon-tooltip-text (object)
Syntax:
(gtk:entry-secondary-icon-tooltip-text object) => text
(setf (gtk:entry-secondary-icon-tooltip-text object) text)
Arguments:
object -- a gtk:entry widget
text -- a string with the contents of the tooltip
Details:
Accessor of the secondary-icon-tooltip-text slot of the gtk:entry class. The contents of the tooltip on the secondary icon. Also see the gtk:entry-icon-tooltip-text function.
See also:
2024-4-7
Accessor gtk:entry-show-emoji-icon (object)
Syntax:
(gtk:entry-show-emoji-icon object) => setting
(setf (gtk:entry-show-emoji-icon object) setting)
Arguments:
object -- a gtk:entry widget
setting -- a boolean whether to show an icon for Emoji
Details:
Accessor of the show-emoji-icon slot of the gtk:entry class. Whether to show an icon for Emoji.
See also:
2024-5-22
Accessor gtk:entry-tabs (object)
Syntax:
(gtk:entry-tabs object) => tabs
(setf (gtk:entry-tabs object) tabs)
Arguments:
object -- a gtk:entry widget
tabs -- a pango:tab-array instance
Details:
Accessor of the tabs slot of the gtk:entry class. The gtk:entry-tabs function gets the tabstops that were set on the text entry using the (setf gtk:entry-tabs) function, if any. The tabstops are applied to the text of the text entry.
See also:
2024-5-22
Accessor gtk:entry-text-length (object)
Syntax:
(gtk:entry-text-length object) => length
Arguments:
object -- a gtk:entry widget
length -- an unsigned integer with the length of the text
Details:
Accessor of the text-length slot of the gtk:entry class. The gtk:entry-text-length function retrieves the current length of the text in the text entry, or 0 if there are none.
Notes:
This function is equivalent to:
(gtk:entry-buffer-length (gtk:entry-buffer object))    
See also:
2024-11-26
Accessor gtk:entry-truncate-multiline (object)
Syntax:
(gtk:entry-truncate-multiline object) => truncate
(setf (gtk:entry-truncate-multiline object) truncate)
Arguments:
object -- a gtk:entry widget
truncate -- a boolean whether multi-line text is truncated
Details:
Accessor of the truncate-multiline slot of the gtk:entry class. If true, pasted multi-line text is truncated to the first line.
See also:
2024-5-22
Accessor gtk:entry-visibility (object)
Syntax:
(gtk:entry-visibility object) => visible
(setf (gtk:entry-visibility object) visible)
Arguments:
object -- a gtk:entry widget
visible -- true if the contents of the text entry are displayed as plaintext
Details:
Accessor of the visibility slot of the gtk:entry class. The gtk:entry-visibility function retrieves whether the text in the text entry is visible. The (setf gtk:entry-visibility) function sets whether the contents of the text entry are visible or not.

When visibility is set to false, characters are displayed as the invisible char, and will also appear that way when the text in the text entry is copied elsewhere. By default, GTK picks the best invisible character available in the current font, but it can be changed with the gtk:entry-invisible-char function.
See also:
2024-5-22
Function gtk:entry-new ()
Returns:
The new gtk:entry widget.
Details:
Creates a new text entry.
See also:
2024-5-22
Function gtk:entry-new-with-buffer (buffer)
Arguments:
buffer -- a gtk:entry-buffer object to use for the text entry
Returns:
The new gtk:entry widget.
Details:
Creates a new text entry with the specified entry buffer.
See also:
2024-5-22
Function gtk:entry-unset-invisible-char (entry)
Arguments:
entry -- a gtk:entry widget
Details:
Unsets the invisible char previously set with the gtk:entry-invisible-char function. So that the default invisible char is used again.
See also:
2024-5-22
Function gtk:entry-alignment (entry)
Syntax:
(gtk:entry-alignment entry) => align
(setf (gtk:entry-alignment entry) align)
Arguments:
entry -- a gtk:entry widget
align -- a number coerced to a float with the horizontal alignment, from 0.0 (left) to 1.0 (right), reversed for RTL layouts
Details:
This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the text entry.
See also:
2024-5-18
Function gtk:entry-progress-pulse (entry)
Arguments:
entry -- a gtk:entry widget
Details:
Indicates that some progress is made, but you do not know how much. Causes the progress indicator of the text entry to enter "activity mode", where a block bounces back and forth. Each call to the gtk:entry-progress-pulse function causes the block to move by a little bit. The amount of movement per pulse is determined by the gtk:entry-progress-pulse-step function.
See also:
#2023-9-16
Function gtk:entry-reset-im-context (entry)
Arguments:
entry -- a gtk:entry widget
Details:
Reset the input method context of the text entry if needed. This can be necessary in the case where modifying the entry buffer would confuse on-going input method behavior.
See also:
#2023-9-16
Function gtk:entry-set-icon-from-paintable (entry pos paintable)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
paintable -- a gdk:paintable object, or nil
Details:
Sets the icon shown in the specified position using a paintable. If the paintable argument is nil, no icon will be shown in the specified position.
See also:
#2023-9-16
Function gtk:entry-set-icon-from-icon-name (entry pos name)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
name -- a string with the icon name, or nil
Details:
Sets the icon shown in the text entry at the specified position from the current icon theme. If the icon name is not known, a "broken image" icon will be displayed instead. If the name argument is nil, no icon will be shown in the specified position.
See also:
#2023-9-16
Function gtk:entry-set-icon-from-gicon (entry pos icon)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
icon -- a g:icon object with the icon to set, or nil
Details:
Sets the icon shown in the text entry at the specified position from the current icon theme. If the icon is not known, a "broken image" icon will be displayed instead.

If the icon argument is nil, no icon will be shown in the specified position.
See also:
#2024-11-26
Function gtk:entry-icon-storage-type (entry pos)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
Returns:
The gtk:image-type value for the image representation being used.
Details:
Gets the type of representation being used by the icon to store image data. If the icon has no image data, the return value will be :empty.
See also:
#2024-11-26
Function gtk:entry-icon-paintable (entry pos)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
Returns:
The gdk:paintable object, or nil if no icon is set for this position.
Details:
Retrieves the paintable used for the icon. If no paintable was used for the icon, nil is returned.
See also:
#2023-9-16
Function gtk:entry-icon-name (entry pos)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
Returns:
The icon name, or nil if no icon is set or if the icon was not set from an icon name.
Details:
Retrieves the icon name used for the icon, or nil if there is no icon or if the icon was set by some other method, for example, by paintable, or gicon.
See also:
#2023-9-16
Function gtk:entry-icon-gicon (entry pos)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
Returns:
The g:icon object, or nil if no icon is set or if the icon is not a g:icon object.
Details:
Retrieves the g:icon object used for the icon, or nil if there is no icon or if the icon was set by some other method, for example, by paintable, or icon name.
See also:
#2023-9-16
Function gtk:entry-icon-activatable (entry pos)
Syntax:
(gtk:entry-icon-activatable entry pos) => activatable
(setf (gtk:entry-icon-activatable entry pos) activatable)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
activatable -- true if the icon is activatable
Details:
The gtk:entry-icon-activatable function returns whether the icon is activatable. The (setf gtk:entry-icon-activatable) function sets whether the icon is activatable.
See also:
#2024-11-26
Function gtk:entry-icon-sensitive (entry pos)
Syntax:
(gtk:entry-icon-sensitive entry pos) => sensitive
(setf (gtk:entry-icon-sensitive entry pos) sensitive)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
sensitive -- specifies whether the icon should appear sensitive or insensitive
Details:
The gtk:entry-icon-sensitive function returns whether the icon appears sensitive or insensitive. The (setf gtk:entry-icon-sensitive) function sets the sensitivity for the specified icon.
See also:
#2023-9-18
Function gtk:entry-icon-at-pos (entry x y)
Arguments:
entry -- a gtk:entry widget
x -- an integer with the x coordinate of the position to find
y -- an integer with the y coordinate of the position to find
Returns:
The integer with the index of the icon at the given position, or -1.
Details:
Finds the icon at the given position and return its index. The coordinates of the posistion are relative to the top left corner of the text entry. If x, y does not lie inside an icon, -1 is returned. This function is intended for use in a "query-tooltip" signal handler.
See also:
#2023-9-16
Function gtk:entry-icon-tooltip-text (entry pos)
Syntax:
(gtk:entry-icon-tooltip-text entry pos) => tooltip
(setf (gtk:entry-icon-tooltip-text entry pos) tooltip)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
tooltip -- a string with the contents of the tooltip for the icon, or nil
Details:
The gtk:entry-icon-tooltip-text function gets the contents of the tooltip on the icon at the specified position in the text entry. The (setf gtk:entry-icon-tooltip-text) function sets a tooltip for the icon at the specified position. Use nil for tooltip to remove an existing tooltip.

See also the gtk:widget-tooltip-text and gtk:entry-icon-tooltip-markup functions.
See also:
#2023-9-18
Function gtk:entry-icon-tooltip-markup (entry pos)
Syntax:
(gtk:entry-icon-tooltip-markup entry pos) => tooltip
(setf (gtk:entry-icon-tooltip-markup entry pos) tooltip)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
tooltip -- a string with the contents of the tooltip for the icon, or nil
Details:
The gtk:entry-icon-tooltip-markup function gets the contents of the tooltip on the icon at the specified position in the text entry. The (setf gtk:entry-icon-tooltip-markup) function sets the tooltip for the icon at the specified position. The tooltip argument is assumed to be marked up with the Pango text markup language. Use nil for tooltip to remove an existing tooltip.

See also the gtk:widget-tooltip-markup and gtk:entry-icon-tooltip-text functions.
See also:
#2023-9-18
Function gtk:entry-set-icon-drag-source (entry pos provider actions)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
provider -- a gdk:content-provider object
actions -- a gdk:drag-action bitmask of the allowed drag actions
Details:
Sets up the icon at the given position so that GTK will start a drag operation when the user clicks and drags the icon.
See also:
#2023-9-16
Function gtk:entry-current-icon-drag-source (entry)
Arguments:
entry -- a gtk:entry widget
Returns:
The integer with the index of the icon which is the source of the current DND operation, or -1.
Details:
Returns the index of the icon which is the source of the current DND operation, or -1.
See also:
#2023-9-16
Function gtk:entry-icon-area (entry pos)
Arguments:
entry -- a gtk:entry widget
pos -- a gtk:entry-icon-position value with the icon position
Returns:
area -- a gdk:rectangle instance with the area of the icon
Details:
Gets the area where the icon of the text entry at pos is drawn. This function is useful when drawing something to the text entry in a draw callback function.

If the text entry is not realized or has no icon at the given position, area is filled with zeros. Otherwise, area will be filled with the allocation of the icon, relative to the allocation of the text entry.
See also:
#2023-9-16
Function gtk:entry-grab-focus-without-selecting (entry)
Arguments:
entry -- a gtk:entry widget
Details:
Causes the text entry to have keyboard focus. It behaves like the gtk:widget-grab-focus function, except that it does not select the contents of the text entry. You only want to call this on some special entries which the user usually does not want to replace all text in, such as search-as-you-type entries.
See also:
#2023-9-16

GtkPasswordEntry

Class gtk:password-entry-buffer
Superclasses:
gtk:entry-buffer, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:entry-buffer object that locks the underlying memory to prevent it from being swapped to disk. The gtk:password-entry widget uses the gtk:password-entry-buffer object.

Since 4.4
See also:
2024-12-5
Function gtk:password-entry-buffer-new ()
Returns:
The newly created gtk:password-entry-buffer object.
Details:
Creates a new gtk:entry-buffer object using secure memory allocations.
See also:
2024-12-5
Class gtk:password-entry
Superclasses:
Documented Subclasses:
None
Direct Slots:
activates-default
The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget, such as the default button in a dialog, when the Enter key is pressed.
Default value: false
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model whose contents will be appended to the context menu.
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the password entry when it is empty and unfocused.
Default value: nil
show-peek-icon
The show-peek-icon property of type :boolean (Read / Write)
Whether to show an icon for revealing the content.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:password-entry class is a text entry that has been tailored for entering secrets.

Figure: GtkPasswordEntry

It does not show its contents in clear text, does not allow to copy it to the clipboard, and it shows a warning when the Caps Lock key is engaged. If the underlying platform allows it, the gtk:password-entry widget will also place the text in a non-pageable memory area, to avoid it being written out to disk by the operating system. Optionally, it can offer a way to reveal the contents in clear text.

The gtk:password-entry widget provides only minimal API and should be used with the gtk:editable API.
CSS Nodes:
entry.password
╰── text
    ├── image.caps-lock-indicator
    ┊    
The gtk:password-entry implementation has a single CSS node with name entry that carries a .passwordstyle style class. The text CSS node below it has a child with name image and .caps-lock-indicator style class for the Caps Lock icon, and possibly other children.
Accessibility:
The gtk:password-entry implementation uses the :text-box role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (entry)    :action      
entry
The gtk:password-entry widget on which the signal is emitted.
A keybinding signal which gets emitted when the user activates the password entry. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control activation programmatically. The default bindings for this signal are all forms of the Enter key.
See also:
2024-12-5
Accessor gtk:password-entry-activates-default (object)
Syntax:
(gtk:password-entry-activates-default object) => setting
(setf (gtk:password-entry-activates-default object) setting)
Arguments:
object -- a gtk:password-entry widget
setting -- true to activate the default widget of the window on Enter keypress
Details:
Accessor of the activates-default slot of the gtk:password-entry class. The gtk:password-entry-activates-default function retrieves whether to activate the default widget, when the Enter key is pressed.

If the setting argument is true, pressing the Enter key in the password entry will activate the default widget for the window containing the password entry. This usually means that the dialog containing the password entry will be closed, since the default widget is usually one of the dialog buttons.
See also:
2024-12-5
Accessor gtk:password-entry-extra-menu (object)
Syntax:
(gtk:password-entry-extra-menu object) => menu
(setf (gtk:password-entry-extra-menu object) menu)
Arguments:
object -- a gtk:password-entry widget
menu -- a g:menu-model object
Details:
Accessor of the extra-menu slot of the gtk:password-entry class. The gtk:password-entry-extra-menu function gets the menu model. The (setf gtk:password-entry-extra-menu) function sets a menu model to add when constructing the context menu for the password entry.
See also:
2024-12-5
Accessor gtk:password-entry-placeholder-text (object)
Syntax:
(gtk:password-entry-placeholder-text object) => text
(setf (gtk:password-entry-placeholder-text object) text)
Arguments:
object -- a gtk:password-entry widget
text -- a string to be displayed when entry is empty and unfocused, or nil
Details:
Accessor of the placeholder-text slot of the gtk:password-entry class. The gtk:password-entry-placeholder-text function retrieves the text that will be displayed when the password entry is empty and unfocused. The (setf gtk:password-entry-placeholder-text) function sets the text. This can be used to give a visual hint of the expected contents of the password entry.

Note that since the placeholder text gets removed when the password entry received focus, using this feature is a bit problematic if the password entry is given the initial focus in a window. Sometimes this can be worked around by delaying the initial focus setting until the first key event arrives.
See also:
2024-12-5
Accessor gtk:password-entry-show-peek-icon (object)
Syntax:
(gtk:password-entry-show-peek-icon object) => setting
(setf (gtk:password-entry-show-peek-icon object) setting)
Arguments:
object -- a gtk:password-entry widget
setting -- a boolean whether to show the peek icon
Details:
Accessor of the show-peek-icon slot of the gtk:password-entry class. The gtk:password-entry-show-peek-icon function returns whether the password entry is showing a clickable icon to reveal the contents of the password entry in clear text. The (setf gtk:password-entry-show-peek-icon) function sets whether the password entry should have a clickable icon. Setting this to false also hides the text again.
See also:
2024-12-5
Function gtk:password-entry-new ()
Returns:
The new gtk:password-entry widget.
Details:
Creates a password entry.
See also:
2024-12-5

GtkScale

Class gtk:scale
Superclasses:
Documented Subclasses:
None
Direct Slots:
digits
The digits property of type :int (Read / Write)
The number of decimal places that are displayed in the value.
Allowed values: [-1, 64]
Default value: 1
draw-value
The draw-value property of type :boolean (Read / Write)
Whether the current value is displayed as a string next to the slider.
Default value: true
has-origin
The has-origin property of type :boolean (Read / Write)
Whether the scale has an origin.
Default value: true
value-pos
The value-pos property of type gtk:position-type (Read / Write)
The position in which the current value is displayed.
Default value: :top
Returned by:
Slot Access Functions:
Details:
The gtk:scale widget is a slider control used to select a numeric value. To use it, you will probably want to investigate the methods on its base gtk:range class, in addition to the methods for the gtk:scale class itself. To set the value of a scale, you would normally use the gtk:range-value function. To detect changes to the value, you would normally use the "value-changed" signal.

Figure: GtkScale

Note that using the same upper and lower bounds for the gtk:scale widget, through the gtk:range methods, will hide the slider itself. This is useful for applications that want to show an undeterminate value on the scale, without changing the layout of the application, such as movie or music players.
GtkScale as GtkBuildable:
The gtk:scale widget supports a custom <marks> element, which can contain multiple <mark> elements. The "value" and "position" attributes have the same meaning as the parameters of the gtk:scale-add-mark function of the same name. If the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual "translatable" and "context" attributes.
CSS nodes:
scale[.fine-tune][.marks-before][.marks-after]
├── [value][.top][.right][.bottom][.left]
├── marks.top
│   ├── mark
│   ┊    ├── [label]
│   ┊    ╰── indicator
┊   ┊
│   ╰── mark
├── marks.bottom
│   ├── mark
│   ┊    ├── indicator
│   ┊    ╰── [label]
┊   ┊
│   ╰── mark
╰── trough
    ├── [fill]
    ├── [highlight]
    ╰── slider    
The gtk:scale implementation has a main CSS node with name scale and a subnode for its contents, with subnodes named trough and slider. The main node gets the .fine-tune style class added when the scale is in 'fine-tuning' mode.

If the scale has an origin, see the gtk:scale-has-origin function, there is a subnode with name highlight below the trough node that is used for rendering the highlighted part of the trough.

If the scale is showing a fill level, see the gtk:range-show-fill-level function, there is a subnode with name fill below the trough node that is used for rendering the filled in part of the trough.

If marks are present, there is a marks subnode before or after the contents node, below which each mark gets a node with name mark. The marks nodes get either the .top or .bottom style class.

The mark node has a subnode named indicator. If the mark has text, it also has a subnode named label. When the mark is either above or left of the scale, the label subnode is the first when present. Otherwise, the indicator subnode is the first.

The main CSS node gets the marks-before and/or marks-after style classes added depending on what marks are present.

If the scale is displaying the value, see the draw-value property, there is subnode with name value. This node will get the .top or .bottom style classes similar to the marks node.
Accessibility:
The gtk:scale implementation uses the :slider role of the gtk:accessible-role enumeration.
See also:
2024-12-5
Accessor gtk:scale-digits (object)
Syntax:
(gtk:scale-digits object) => digits
(setf (gtk:scale-digits object) digits)
Arguments:
object -- a gtk:scale widget
digits -- an integer with the number of decimal places to display
Details:
Accessor of the digits slot of the gtk:scale class. The gtk:scale-digits function returns the number of decimal places that are displayed. The (setf gtk:scale-digits) function sets the number of decimal places. Also causes the value of the adjustment to be rounded off to this number of digits, so the retrieved value matches the value the user saw.
See also:
2024-12-5
Accessor gtk:scale-draw-value (object)
Syntax:
(gtk:scale-draw-value object) => setting
(setf (gtk:scale-digits object) setting)
Arguments:
object -- a gtk:scale widget
setting -- true to draw the value
Details:
Accessor of the draw-value slot of the gtk:scale class. The gtk:scale-draw-value function returns whether the current value is displayed as a string next to the slider. The (setf gtk:scale-draw-value) function specifies whether the current value is displayed as a string next to the slider.
See also:
2024-12-5
Accessor gtk:scale-has-origin (object)
Syntax:
(gtk:scale-has-origin object) => setting
(setf (gtk:scale-digits object) setting)
Arguments:
object -- a gtk:scale widget
setting -- true if the scale has an origin
Details:
Accessor of the has-origin slot of the gtk:scale class. The gtk:scale-has-origin function returns whether the scale has an origin.

If the has-origin property is set to true, the default, the scale will highlight the part of the scale between the origin, bottom or left side, of the scale and the current value.
See also:
2024-12-5
Accessor gtk:scale-value-pos (object)
Syntax:
(gtk:scale-value-pos object) => pos
(setf (gtk:scale-digits object) pos)
Arguments:
object -- a gtk:scale widget
pos -- a gtk:position-type value with the position in which the current value is displayed
Details:
Accessor of the value-pos slot of the gtk:scale class. The gtk:scale-value-pos function gets the position in which the current value is displayed. The (setf gtk:scale-value-pos) function sets the position.
See also:
2024-12-5
Function gtk:scale-new (orientation adjustment)
Arguments:
orientation -- a value of the gtk:orientation enumeration
adjustment -- a gtk:adjustment object which sets the range of the scale, or nil to create a new adjustment
Returns:
The new gtk:scale widget.
Details:
Creates a new scale widget.
See also:
2024-12-5
Function gtk:scale-new-with-range (orientation min max step)
Arguments:
orientation -- a value of the gtk:orientation enumeration
min -- a number coerced to a double float with the minimum value
max -- a number coerced to a double float with the maximum value
step -- a number coerced to a double float with the step increment, tick size, used with keyboard shortcuts
Returns:
The new gtk:scale widget.
Details:
Creates a new scale widget with the given orientation that lets the user input a number between min and max, including min and max, with the increment step. The step argument must be nonzero. It is the distance the slider moves when using the arrow keys to adjust the scale value.

Note that the way in which the precision is derived works best if the step argument is a power of ten. If the resulting precision is not suitable for your needs, use the gtk:scale-digits function to correct it.
See also:
2024-12-5
Callback gtk:scale-format-value-func
Syntax:
lambda (scale value) => result
Arguments:
scale -- a gtk:scale widget
value -- a double float with the numeric value to format
result -- a string describing a textual representation of the given numerical value
Details:
A callback function that formats the value of a scale. The callback function is set with the gtk:scale-set-format-value-func function.
See also:
2024-12-5
Function gtk:scale-set-format-value-func (scale func)
Arguments:
scale -- a gtk:scale widget
func -- a gtk:scale-format-value-func callback function that formats the value
Details:
The func callback function allows you to change how the scale value is displayed. The given function will return a string representing the value. That string will then be used to display the value of the scale.

If nil is passed as func, the value will be displayed on its own, rounded according to the value of the digits property.
See also:
2024-12-5
Function gtk:scale-layout (scale)
Arguments:
scale -- a gtk:scale widget
Returns:
The pango:layout instance for this scale, or nil if the draw-value property is false.
Details:
Gets the Pango layout used to display the current value of the scale.
See also:
2024-12-5
Function gtk:scale-layout-offsets (scale)
Arguments:
scale -- a gtk:scale widget
Returns:
x -- an integer with the x offset of the Pango layout
y -- an integer with the y offset of the Pango layout
Details:
Obtains the coordinates where the scale will draw the Pango layout representing the text in the scale. Remember when using the pango:layout functions you need to convert to and from pixels using the pango:pixels function or the pango:+scale+ constant. If the draw-value property is false, the return values are undefined.
See also:
2024-12-5
Function gtk:scale-add-mark (scale value pos &optional markup)
Arguments:
scale -- a gtk:scale widget
value -- a number coerced to a double float with the value at which the mark is placed, must be between the lower and upper limits of the adjustment of the scale
pos -- a value of the gtk:position-type enumeration
markup -- a string with the text to be shown at the mark, using Pango markup, or the default nil value
Details:
Adds a mark at value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK makes it easy for the user to position the scale exactly at the marks value. For a horizontal scale, :top and :left are drawn above the scale, anything else below. For a vertical scale, :left and :top are drawn to the left of the scale, anything else to the right.

If the markup argument is not nil, text is shown next to the tick mark. To remove marks from a scale, use the gtk:scale-clear-marks function.
See also:
2024-12-5
Function gtk:scale-clear-marks (scale)
Arguments:
scale -- a gtk:scale widget
Details:
Removes any marks that have been added with the gtk:scale-add-mark function.
See also:
2024-12-5

GtkSpinButton

GEnum gtk:spin-button-update-policy
Declaration:
(gobject:define-genum "GtkSpinButtonUpdatePolicy" spin-button-update-policy
  (:export t
   :type-initializer "gtk_spin_button_update_policy_get_type")
  (:always 0)
  (:if-valid 1))  
Values:
:always
When refreshing the spin button, the value is always displayed
:if-valid
When refreshing the spin button, the value is only displayed if it is valid within the bounds of the spin button's adjustment.
Details:
The spin button update policy determines whether the spin button displays values even if they are outside the bounds of its adjustment. See the gtk:spin-button-update-policy function.
See also:
2023-9-30
GEnum gtk:spin-type
Declaration:
(gobject:define-genum "GtkSpinType" spin-type
  (:export t
   :type-initializer "gtk_spin_type_get_type")
  (:step-forward 0)
  (:step-backward 1)
  (:page-forward 2)
  (:page-backward 3)
  (:home 4)
  (:end 5)
  (:user-defined 6))  
Values:
:step-forward
Increment by the adjustments step increment.
:step-backward
Decrement by the adjustments step increment.
:page-forward
Increment by the adjustments page increment.
:page-backward
Decrement by the adjustments page increment.
:home
Go to the adjustments lower bound.
:end
Go to the adjustments upper bound.
:user-defined
Change by a specified amount.
Details:
The values of the gtk:spin-type enumeration are used to specify the change to make in the gtk:spin-button-spin function.
See also:
2023-9-30
Class gtk:spin-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
activates-default
The activates-default property of type gboolean (Read / Write)
Whether to activate the default widget when the spin button is activated. Since 4.16
Default value: false
adjustment
The adjustment property of type gtk:adjustment (Read / Write)
The adjustment that holds the value of the spin button.
climb-rate
The climb-rate property of type :double (Read / Write)
The acceleration rate when you hold down a button.
Allowed values: >= 0
Default value: 0
digits
The digits property of type :uint (Read / Write)
The number of decimal places to display.
Allowed values: <= 20
Default value: 0
numeric
The numeric property of type :boolean (Read / Write)
Whether non numeric characters should be ignored.
Default value: false
snap-to-ticks
The snap-to-ticks property of type :boolean (Read / Write)
Whether erroneous values are automatically changed to a spin button's nearest step increment.
Default value: false
update-policy
The update-policy property of type gtk:spin-button-update-policy (Read / Write)
Whether the spin button should update always, or only when the value is legal.
Default value: :always
value
The value property of type :double (Read / Write)
Reads the current value, or sets a new value.
Default value: 0.0
wrap
The wrap property of type :boolean (Read / Write)
Whether a spin button should wrap upon reaching its limits.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:spin-button widget is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a gtk:entry widget, the spin button allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range.

Figure: GtkSpinButton

The main properties of a gtk:spin-button widget are through an adjustment. See the gtk:adjustment class for more details about the properties of an adjustment.

Note that the gtk:spin-button widget will by default make its entry large enough to accommodate the lower and upper bounds of the adjustment. If this is not desired, the automatic sizing can be turned off by explicitly setting the width-chars property to a value not equal to -1.
CSS nodes:
spinbutton.horizontal
├── undershoot.left
├── undershoot.right
├── entry
│   ╰── ...
├── button.down
╰── button.up

spinbutton.vertical ├── undershoot.left ├── undershoot.right ├── button.up ├── entry │ ╰── ... ╰── button.down
The gtk:spin-button implementation main CSS node has the name spinbutton. It creates subnodes for the text entry and the two buttons, with these names. The button nodes have the .up and .down style classes. The gtk:entry subnodes, if present, are put below the text entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node.
Examples:
Code fragment for creating a spin button. The value from the spin button is retrieved with the gtk:spin-button-value function in a signal handler as a floating point number. Use the gtk:spin-button-value-as-int function to retrieve the value as an integer.
(let (...
      (spinner (make-instance 'gtk:spin-button
                              :adjustment
                              (make-instance 'gtk:adjustment
                                             :value 50.0
                                             :lower 0.0
                                             :upper 100.0
                                             :step-increment 1.0
                                             :page-increment 5.0
                                             :page-size 0.0)
                              :climb-rate 0
                              :digits 0
                              :wrap t)))

(g:signal-connect spinner "value-changed" (lambda (widget) (let ((value (gtk:spin-button-value widget))))) ... ))
Accessibility:
The gtk:spin-button implementation uses the :spin-button role of the gtk:accessible-role enumeration.
Signal Details:
The "change-value" signal
lambda (button scroll)    :action      
button
The gtk:spin-button widget on which the signal was emitted.
scroll
The value of the gtk:scroll-type enumeration to specify the speed and amount of change.
Keybinding signal which gets emitted when the user initiates a value change. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp and PageDown.
The "input" signal
lambda (button value)    :run-last      
button
The gtk:spin-button widget on which the signal was emitted.
value
The pointer to a double float with the return location for the new value.
Returns
True for a successful conversion, false if the input was not handled, and -1 if the conversion failed.
Can be used to influence the conversion of the users input into a double float. The signal handler is expected to use the gtk:editable-text function to retrieve the text of the text entry and set value to the new value. The default conversion uses the g_strtod() function.
The "output" signal
lambda (button)    :run-last      
button
The gtk:spin-button widget which received the signal.
Returns
True if the value has been displayed.
Can be used to change the formatting of the value that is displayed in the spin buttons entry.
(let (...
      ;; A spin button for a number
      (spinner1 (make-instance 'gtk:spin-button
                               :adjustment
                               (make-instance 'gtk:adjustment
                                              :value 1.0
                                              :lower -10000.0
                                              :upper  10000.0
                                              :step-increment 0.5
                                              :page-increment 100.0
                                              :page-size 0.0)
                               :climb-rate 1.0
                               :digits 2
                               :wrap t))
      ;; A spin button for the digits to display
      (spinner2 (make-instance 'gtk:spin-button
                               :adjustment
                               (make-instance 'gtk:adjustment
                                              :value 2
                                              :lower 1
                                              :upper 5
                                              :step-increment 1
                                              :page-increment 1
                                              :page-size 0)
                                :climb-rate 0.0
                                :digits 0
                                :wrap t)))
  ;; Customize the appearance of the number
  (g:signal-connect spinner1 "output"
    (lambda (spinbutton)
      (let ((value (gtk:adjustment-value
                     (gtk:spin-button-adjustment spinbutton)))
            (digits (truncate
                      (gtk:adjustment-value
                        (gtk:spin-button-adjustment spinner2)))))
        (setf (gtk:entry-text spinbutton)
              (format nil "~@?" (format nil "~~,~d@f" digits) value)))))
  ... )      
The "value-changed" signal
lambda (button)    :run-last      
button
The gtk:spin-button widget on which the signal was emitted.
Is emitted when the value represented by button changes. Also see the "output" signal.
The "wrapped" signal
lambda (button)    :run-last      
button
The gtk:spin-button widget which received the signal.
Is emitted right after the spin button wraps from its maximum to minimum value or vice versa.
See also:
2024-5-26
Accessor gtk:spin-button-activates-default (object)
Syntax:
(gtk:spin-button-activates-default object) => setting
(setf (gtk:spin-button-adjustment object) setting)
Arguments:
object -- a gtk:spin-button widget
setting -- true to activate the default widget on activation
Details:
Accessor of the activates-default slot of the gtk:spin-button class. The gtk:spin-button-activates-default function gets whether activating the spin button will activate the default widget for the window containing the spin button. The (setf gtk:spin-button-activates-default) function sets the property.

Since 4.14
See also:
2024-5-26
Accessor gtk:spin-button-adjustment (object)
Syntax:
(gtk:spin-button-adjustment object) => adjustment
(setf (gtk:spint-button-adjustment object) adjustment)
Arguments:
object -- a gtk:spin-button widget
adjustment -- a gtk:adjustment object to replace the existing adjustment
Details:
Accessor of the adjustment slot of the gtk:spin-button class. The gtk:spin-button-adjustment function gets the adjustment associated with a spin button. The (setf gtk:spin-button-adjustment) function replaces the adjustment.
See also:
2023-9-30
Accessor gtk:spin-button-climb-rate (object)
Syntax:
(gtk:spin-button-climb-rate object) => climb-rate
(setf (gtk:spint-button-climb-rate object) climb-rate)
Arguments:
object -- a gtk:spin-button widget
climb-rate -- a double float with the acceleration rate
Details:
Accessor of the climb-rate slot of the gtk:spin-button class. The gtk:spin-button-climb-rate function gets the acceleration rate when you hold down a button. The (setf gtk:spin-button-climb-rate) function sets the acceleration rate.
See also:
2023-9-30
Accessor gtk:spin-button-digits (object)
Syntax:
(gtk:spin-button-digits object) => digits
(setf (gtk:spint-button-digits object) digits)
Arguments:
object -- a gtk:spin-button widget
digits -- an unsigned integer with the number of digits after the decimal point to be displayed for the spin button's value
Details:
Accessor of the digits slot of the gtk:spin-button class. The gtk:spin-button-digits function fetches the precision to be displayed by the spin button. The (setf gtk:spin-button-digits) function sets the precision. Up to 20 digit precision is allowed.
See also:
2023-9-30
Accessor gtk:spin-button-numeric (object)
Syntax:
(gtk:spin-button-numeric object) => numeric
(setf (gtk:spin-button-numeric object) numeric)
Arguments:
object -- a gtk:spin-button widget
numeric -- a boolean indicating if only numeric entry is allowed
Details:
Accessor of the numeric slot of the gtk:spin-button class. The gtk:spin-button-numeric function returns whether non numeric text can be typed into the spin button. The (setf gtk:spin-button-numeric) function sets the flag.
See also:
2023-9-30
Accessor gtk:spin-button-snap-to-ticks (object)
Syntax:
(gtk:spin-button-snap-to-ticks object) => snap-to-ticks
(setf (gtk:spin-button-snap-to-ticks object) snap-to-ticks)
Arguments:
object -- a gtk:spin-button widget
snap-to-ticks -- a boolean indicating if invalid values should be corrected
Details:
Accessor of the snap-to-ticks slot of the gtk:spin-button class. The gtk:spin-button-snap-to-ticks function returns whether the values are corrected to the nearest step. The (setf gtk:spin-button-snap-to-ticks) function sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value.
See also:
2023-9-30
Accessor gtk:spin-button-update-policy (object)
Syntax:
(gtk:spin-button-update-policy object) => update-policy
(setf (gtk:spin-button-upadate-policy object) update-policy)
Arguments:
object -- a gtk:spin-button widget
policy -- a value of the gtk:spin-button-update-policy enumeration
Details:
Accessor of the update-policy slot of the gtk:spin-button class. The gtk:spin-button-update-policy function gets the update behavior of a spin button. The (setf gtk:spin-button-update-policy) function sets the update behavior. This determines whether the spin button is always updated or only when a valid value is set.
See also:
2023-9-30
Accessor gtk:spin-button-value (object)
Syntax:
(gtk:spin-button-value object) => value
(setf (gtk:spin-button-value object) value)
Arguments:
object -- a gtk:spin-button widget
value -- a double float with the value of the spin button
Details:
Accessor of the value slot of the gtk:spin-button class. The gtk:spin-button-value function gets the value of the spin button. The (setf gtk:spin-button-value) function sets the value.
See also:
2023-9-30
Accessor gtk:spin-button-wrap (object)
Syntax:
(gtk:spin-button-value object) => wrap
(setf (gtk:spin-button-value object) wrap)
Arguments:
object -- a gtk:spin-button widget
wrap -- a boolean indicating if wrapping behavior is performed
Details:
Accessor of the wrap slot of the gtk:spin-button class. The gtk:spin-button-wrap function returns whether the value of the spin button wraps around to the opposite limit when the upper or lower limit of the range is exceeded. The (setf gtk:spin-button-wrap) function sets the flag that determines if a spin button value wraps around.
See also:
2023-9-30
Function gtk:spin-button-new (adjustment climb-rate digits)
Arguments:
adjustment -- a gtk:adjustment object that this spin button should use, or nil
climb-rate -- a double float which specifies how much the spin button changes when an arrow is clicked on
digits -- an unsigned integer with the number of decimal places to display
Returns:
The new gtk:spin-button widget.
Details:
Creates a new spin button. If the adjustment argument is nil, the adjustment of the spin button is intialized with default values.
See also:
2023-9-30
Function gtk:spin-button-new-with-range (min max step)
Arguments:
min -- a double float with the minimum allowable value
max -- a double float with the maximum allowable value
step -- a double float with the increment added or subtracted by spinning the widget
Returns:
The new gtk:spin-button widget.
Details:
This is a convenience constructor that allows creation of a numeric spin button without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * step is the default. The precision of the spin button is equivalent to the precision of step.

The way in which the precision is derived works best if step is a power of ten. If the resulting precision is not suitable for your needs, use the gtk:spin-button-digits function to correct it.
Notes:
In the Lisp implementation the min, max, and step arguments are coerced to a double float number.
Examples:
In this example the arguments of the function are given as integer numbers.
(defvar spinbutton (gtk:spin-button-new-with-range 5 15 5)) => SPINBUTTON
;; Get the adjustment of the spin button
(defvar adjustment (gtk:spin-button-adjustment spinbutton)) => ADJUSTMENT
;; Get the slots of the adjustment of the spin button
(gtk:adjustment-lower adjustment) => 5.0d0
(gtk:adjustment-page-increment adjustment) => 50.0d0
(gtk:adjustment-page-size adjustment) => 0.0d0
(gtk:adjustment-step-increment adjustment) => 5.0d0
(gtk:adjustment-upper adjustment) => 15.0d0
(gtk:adjustment-value adjustment) =>5.0d0    
See also:
2023-9-30
Function gtk:spin-button-increments (button)
Syntax:
(gtk:spin-button-increments button) => step, page
(setf (gtk:spin-button-increments button) (list step page))
Arguments:
button -- a gtk:spin-button widget
step -- a double float increment applied for a button 1 press
page -- a double float increment applied for a button 2 press
Details:
The gtk:spin-button-increments function gets the current step and page increments used by the spin button. The (setf gtk:spin-button-increments) function sets the step and page increments.

This affects how quickly the value changes when the arrows of the spin button are activated.
Notes:
The values for the page and step increments are stored in the page-increment and step-increment properties of the adjustment associated with the spin button.
See also:
#2023-9-30
Function gtk:spin-button-range (button)
Syntax:
(gtk:spin-button-range button) => min, max
(setf (gtk:spin-button-range button) (list min max))
Arguments:
button -- a gtk:spin-button widget
min -- a double float minimum allowable value
max -- a double float maximum allowable value
Details:
The gtk:spin-button-range function gets the minimum and maximum allowed values for the spin button. The (setf gtk:spin-button-range) function sets the minimum and maximum allowable values.

If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged.
See also:
#2023-9-30
Function gtk:spin-button-value-as-int (button)
Arguments:
button -- a gtk:spin-button widget
Returns:
The integer with the value of button.
Details:
Gets the value of the spin button represented as an integer.
See also:
#2023-9-30
Function gtk:spin-button-configure (button adjustment climb-rate digits)
Arguments:
button -- a gtk:spin-button widget
adjustment -- a gtk:adjustment object
climb-rate -- a double float with the climb rate
digits -- an unsigned integer with the number of decimal places to display in the spin button
Details:
Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call.
See also:
#2023-9-30
Function gtk:spin-button-spin (button direction increment)
Arguments:
button -- a gtk:spin-button widget
direction -- a value of the gtk:spin-type enumeration indicating the direction to spin
increment -- a double float step increment to apply in the specified direction
Details:
Increment or decrement the value of the spin button in a specified direction by a specified amount.
See also:
#2023-9-30
Function gtk:spin-button-update (button)
Arguments:
button -- a gtk:spin-button widget
Details:
Manually force an update of the spin button.
See also:
#2023-9-30

GtkSearchEntry

Class gtk:search-entry
Superclasses:
Documented Subclasses:
None
Direct Slots:
activates-default
The activates-default property of type :boolean (Read / Write)
Whether to activate the default widget, such as the default button in a dialog, when the Enter key is pressed.
Default value: false
input-hints
The input-hints property of type gtk:input-hints (Read / Write)
The hints about input for the search entry used to alter the behaviour of input methods. Since 4.14
Default value: :none
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose for the search entry input used to alter the behaviour of input methods. Since 4.14
Default value: :free-form
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the text entry when it is empty and unfocused.
Default value: nil
search-delay
The search-delay property of type :uint (Read / Write)
The delay in milliseconds from last keypress to the search changed signal.
Default value: 150
Returned by:
Slot Access Functions:
Details:
The gtk:search-entry widget is a text entry that has been tailored for use as a search entry. The main API for interacting with a gtk:search-entry widget as entry is the gtk:editable interface.

Figure: GtkSearchEntry

It will show an inactive symbolic find icon when the search entry is empty, and a symbolic clear icon when there is text. Clicking on the clear icon will empty the search entry.

To make filtering appear more reactive, it is a good idea to not react to every change in the search entry text immediately, but only after a short delay. To support this, the gtk:search-entry widget emits the "search-changed" signal which can be used instead of the "changed" signal.

The "previous-match", "next-match" and "stop-search" signals can be used to implement moving between search results and ending the search.

Often, the gtk:search-entry widget will be fed events by means of being placed inside a gtk:search-bar widget. If that is not the case, you can use the gtk:search-entry-key-capture-widget function to let it capture key input from another widget.
CSS Nodes:
entry.search
╰── text    
The gtk:search-entry implementation has a single CSS node with name entry that carries a .search style class, and the text node is a child of that.
Accessibility:
The gtk:search-entry implementation uses the :search-box role of the gtk:accessible-role enumeration.
Signal Details:
The "activate" signal
lambda (entry)    :action      
entry
The gtk:search-entry widget on which the signal is emitted.
The signal is forwarded from the "activated" signal, which is a keybinding signal for all forms of the Enter key.
The "next-match" signal
lambda (entry)    :action      
entry
The gtk:search-entry widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted when the user initiates a move to the next match for the current search string. Applications should connect to it, to implement moving between matches. The default bindings for this signal is the Ctrl-g key.
The "previous-match" signal
lambda (entry)    :action      
entry
The gtk:search-entry widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted when the user initiates a move to the previous match for the current search string. Applications should connect to it, to implement moving between matches. The default bindings for this signal is the Ctrl-Shift-g key.
The "search-changed" signal
lambda (entry)    :run-last      
entry
The gtk:search-entry widget on which the signal is emitted.
The signal is emitted with a short delay of 150 milliseconds after the last change to the text entry.
The "stop-search" signal
lambda (entry)    :action      
entry
The gtk:search-entry widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted when the user stops a search via keyboard input. Applications should connect to it, to implement hiding the search entry in this case. The default bindings for this signal is the Escape key.
See also:
2024-5-26
Accessor gtk:search-entry-activates-default (object)
Syntax:
(gtk:search-entry-activates-default object) => setting
(setf (gtk:search-entry-activates-default object) setting)
Arguments:
object -- a gtk:search-entry widget
setting -- true to activate the default widget of the window on Enter keypress
Details:
Accessor of the activates-default slot of the gtk:search-entry class. The gtk:search-entry-activates-default function retrieves whether to activate the default widget, when the Enter key is pressed.

If the setting argument is true, pressing the Enter key in the search entry will activate the default widget for the window containing the search entry. This usually means that the dialog containing the search entry will be closed, since the default widget is usually one of the dialog buttons.
See also:
2024-5-22
Accessor gtk:search-entry-input-hints (object)
Syntax:
(gtk:search-entry-input-hints object) => hints
(setf (gtk:search-entry-input-hints object) hints)
Arguments:
object -- a gtk:search-entry widget
hints -- a gtk:input-hints value
Details:
Accessor of the input-hints slot of the gtk:search-entry class. The gtk:search-entry-input-hints function gets the input hints for the search entry. The (setf gtk:search-entry-input-hints) function sets the input hints.

Since 4.14
See also:
2024-5-26
Accessor gtk:search-entry-input-purpose (object)
Syntax:
(gtk:search-entry-input-purpose object) => purpose
(setf (gtk:search-entry-input-purpose object) purpose)
Arguments:
object -- a gtk:search-entry widget
purpose -- a gtk:input-purpose value
Details:
Accessor of the input-purpose slot of the gtk:search-entry class. The gtk:search-entry-input-purpose function gets the input purpose of the search entry. The (setf gtk:search-entry-input-purpose) function sets the input purpose.

Since 4.14
See also:
2024-5-26
Accessor gtk:search-entry-placeholder-text (object)
Syntax:
(gtk:search-entry-placeholder-text object) => text
(setf (gtk:search-entry-placeholder-text object) text)
Arguments:
object -- a gtk:search-entry widget
text -- a string to be displayed when entry is empty and unfocused, or nil
Details:
Accessor of the placeholder-text slot of the gtk:search-entry class. The gtk:search-entry-placeholder-text function retrieves the text that will be displayed when the search entry is empty and unfocused. The (setf gtk:search-entry-placeholder-text) function sets the text. This can be used to give a visual hint of the expected contents of the search entry.

Note that since the placeholder text gets removed when the search entry received focus, using this feature is a bit problematic if the search entry is given the initial focus in a window. Sometimes this can be worked around by delaying the initial focus setting until the first key event arrives.
See also:
2024-4-20
Accessor gtk:search-entry-search-delay (object)
Syntax:
(gtk:search-entry-search-delay object) => delay
(setf (gtk:search-entry-search-delay object) delay)
Arguments:
object -- a gtk:search-entry widget
delay -- an unsigned integer with the delay in milliseconds
Details:
Accessor of the search-delay slot of the gtk:search-entry class. The gtk:search-entry-search-delay function gest the delay to be used between the last keypress and the "search-changed" signal being emitted. The (setf gtk:search-entry-search-delay) function sets the search delay.

Since 4.8
See also:
2024-4-20
Function gtk:search-entry-new ()
Returns:
The new gtk:search-entry widget.
Details:
Creates a search entry, with a find icon when the search field is empty, and a clear icon when it is not.
See also:
2024-4-20
Function gtk:search-entry-key-capture-widget (entry)
Syntax:
(gtk:search-entry-key-capture-widget entry) => widget
(setf (gtk:search-entry-key-capture-widget entry) widget)
Arguments:
entry -- a gtk:search-entry widget
widget -- a gtk:widget key capture widget
Details:
Accessor of the key capture widget of the search entry. The gtk:search-entry-key-capture-widget function gets the widget that the search entry is capturing key events from. The (setf gtk:search-entry-key-capture-widget) function sets widget as the widget that the search entry will capture key events from.

Key events are consumed by the search entry to start or continue a search.

If the search entry is part of a gtk:search-bar widget, it is preferable to call the gtk:search-bar-key-capture-widget function instead, which will reveal the text entry in addition to triggering the search entry.
See also:
#2024-4-20

GtkSearchBar

Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write / Construct)
The child widget of the search bar.
key-capture-widget
The key-capture-widget property of type gtk:widget (Read / Write / Construct)
The widget that the search bar will capture key events from.
search-mode-enabled
The search-mode-enabled property of type :boolean (Read / Write)
Whether the search mode is on and the search bar shown.
Default value: false
show-close-button
The show-close-button property of type :boolean (Read / Write / Construct)
Whether to show the Close button in the toolbar.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:search-bar widget is a container made to have a search entry. It can also contain additional widgets, such as drop-down menus, or buttons. The search bar would appear when a search is started through typing on the keyboard, or the search mode of the application is toggled on.

Figure: GtkSearchBar

For keyboard presses to start a search, the search bar must be told of a widget to capture key events from through the gtk:search-bar-key-capture-widget function. This widget will typically be the toplevel window, or a parent container of the search bar. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items.

You will also need to tell the search bar about which entry you are using as your search entry using the gtk:search-bar-connect-entry function.
Examples:
The following example shows you how to create a more complex search entry.
(defun do-search-bar (&optional application)
  (let* ((box (make-instance 'gtk:box
                             :orientation :horizontal
                             :spacing 6))
         (searchbar (make-instance 'gtk:search-bar
                                   :child box
                                   :valign :start))
         (window (make-instance 'gtk:window
                                :title "Search Bar"
                                :application application
                                :child searchbar))
         (entry (make-instance 'gtk:search-entry
                               :hexpand t))
         (button (make-instance 'gtk:menu-button)))
    (gtk:search-bar-connect-entry searchbar entry)
    (setf (gtk:search-bar-key-capture-widget searchbar) window)
    (gtk:box-append box entry)
    (gtk:box-append box button)
    (gtk:window-present window)))    
CSS nodes:
searchbar
╰── revealer
    ╰── box
         ├── [child]
         ╰── [button.close]    
The gtk:search-bar implementation has a single CSS node with name searchbar. It has a child node with name revealer that contains a node with name box. The box node contains both the CSS node of the child widget as well as an optional button node which gets the .close style class applied.
Accessibility:
The gtk:search-bar implementation uses the :search role of the gtk:accessible-role enumeration.
See also:
2024-4-20
Accessor gtk:search-bar-child (object)
Syntax:
(gtk:search-bar-child object) => child
(setf (gtk:search-bar-child object) child)
Arguments:
object -- a gtk:search-bar widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:search-bar class. The gtk:search-bar-child function gets the child widget of the search bar. The (setf gtk:search-bar-child) function sets the child widget.
See also:
2024-4-20
Accessor gtk:search-bar-key-capture-widget (object)
Syntax:
(gtk:search-bar-key-capture-widget object) => widget
(setf (gtk:search-bar-key-capture-widget object) widget)
Arguments:
object -- a gtk:search-bar widget
widget -- a gtk:widget key capture widget
Details:
Accessor of the key-capture-widget slot of the gtk:search-bar class. The gtk:search-bar-key-capture-widget function gets the widget that the search bar is capturing key events from. The (setf gtk:search-bar-key-capture-widget) function sets widget as the widget that the search bar will capture key events from.

If key events are handled by the search bar, the search bar will be shown, and the search entry populated with the entered text.
See also:
2024-4-20
Accessor gtk:search-bar-search-mode-enabled (object)
Syntax:
(gtk:search-bar-search-mode-enabled object) => mode
(setf (gtk:search-bar-search-mode-enabled object) mode)
Arguments:
object -- a gtk:search-bar widget
mode -- a boolean with the state of the search mode
Details:
Accessor of the search-mode-enabled slot of the gtk:search-bar class. Switches the search mode on or off.
See also:
2024-4-20
Accessor gtk:search-bar-show-close-button (object)
Syntax:
(gtk:search-bar-show-close-button object) => visible
(setf (gtk:search-bar-show-close-button object) visible)
Arguments:
object -- a gtk:search-bar widget
visible -- a boolean whether the Close button will be shown or not
Details:
Accessor of the show-close-button slot of the gtk:search-bar class. The gtk:search-bar-show-close-button function returns whether the Close button is shown. The (setf gtk:search-bar-show-close-button) function shows or hides the Close button.

Applications that already have a search toggle button should not show a Close button in their search bar, as it duplicates the role of the toggle button.
See also:
2024-4-20
Function gtk:search-bar-new ()
Returns:
The new gtk:search-bar widget.
Details:
Creates a search bar. You will need to tell it about which widget is going to be your text entry using the gtk:search-bar-connect-entry function.
See also:
2024-4-20
Function gtk:search-bar-connect-entry (searchbar entry)
Arguments:
searchbar -- a gtk:search-bar widget
entry -- a gtk:entry widget
Details:
Connects the text entry passed as the one to be used in the search bar. The text entry should be a descendant of the search bar. This is only required if the text entry is not the direct child of the search bar, as in our main example.
See also:
2024-4-20

GtkEditableLabel

Class gtk:editable-label
Superclasses:
Documented Subclasses:
None
Direct Slots:
editing
The editing property of type :boolean (Read)
The property is true while the widget is in edit mode.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:editable-label widget is a gtk:label widget that allows users to edit the text by switching the widget to an "edit mode".

Figure: GtkEditableLabel

The gtk:editable-label widget does not have API of its own, but it implements the gtk:editable interface.

The default bindings for activating the edit mode is to click or press the Enter key. The default bindings for leaving the edit mode are the Enter key, to save the results, or the Escape key, to cancel the editing.
CSS Nodes:
editablelabel[.editing]
╰── stack
    ├── label
    ╰── text    
The gtk:editable-label implementation has a main node with the name editablelabel. When the text entry is in editing mode, it gets the .editing style class. For all the subnodes added to the text node in various situations, see the gtk:text documentation.
Action Details:
The "editing.stop" action
Switch the widget out of editing mode. If commit is true, then the results of the editing are taken as the new value of the text property. The default binding for this action is the Escape key. This action is disabled when the editing property is false.
commit
The boolean whether to make changes permanent.
The "editing.start" action
Switch the widget into editing mode, so that the user can make changes to the text. The default bindings for this action are clicking on the widget and the Enter key. This action is disabled when the editing property is false.
See also:
2024-5-23
Accessor gtk:editable-label-editing (object)
Syntax:
(gtk:editable-label-editing object) => setting
(setf (gtk:editable-label-editing object) setting)
Arguments:
object -- a gtk:editable-label widget
setting -- a boolean whether the label is currently in editing mode
Details:
Accessor of the editing slot of the gtk:editable-label class. The gtk:editable-label-editing function returns whether the label is currently in editing mode.
See also:
2024-5-23
Function gtk:editable-label-new (text)
Arguments:
text -- a string with the text for the label
Returns:
The new gtk:editable-label widget.
Details:
Creates a new editable label.
See also:
2024-5-23
Function gtk:editable-label-start-editing (label)
Arguments:
label -- a gtk:editable-label widget
Details:
Switches the label into "editing mode".
See also:
#2023-5-4
Function gtk:editable-label-stop-editing (label commit)
Arguments:
label -- a gtk:editable-label widget
commit -- a boolean whether to set the edited text on the label
Details:
Switches the label out of “editing mode”. If commit is true, the resulting text is kept as the text property value, otherwise the resulting text is discarded and the label will keep its previous text property value.
See also:
#2023-5-4

Multiline Text Editor

Conceptual Overview

GTK has a powerful framework for multiline text editing. The primary objects involved in the process are the gtk:text-buffer object, which represents the text being edited, and the gtk:text-view widget, a widget which can display a gtk:text-buffer object. Each text buffer can be displayed by any number of views.

One of the important things to remember about text in GTK is that it is in the UTF-8 encoding. This means that one character can be encoded as multiple bytes. Character counts are usually referred to as offsets, while byte counts are called indexes. If you confuse these two, things will work fine with ASCII, but as soon as your text buffer contains multibyte characters, bad things will happen.

Text in a text buffer can be marked with tags. A tag is an attribute that can be applied to some range of text. For example, a tag might be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that. Tags do not have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user cannot edit it, or countless other things. A tag is represented by a gtk:text-tag object. One gtk:text-tag object can be applied to any number of text ranges in any number of text buffers.

Each tag is stored in a gtk:text-tag-table object. A tag table defines a set of tags that can be used together. Each text buffer has one tag table associated with it. Only tags from that tag table can be used with the text buffer. A single tag table can be shared between multiple text buffers, however. Tags can have names, which is convenient sometimes. For example, you can name your tag that makes things bold "bold", but they can also be anonymous, which is convenient if you are creating tags on-the-fly.

Most text manipulation is accomplished with iterators, represented by a gtk:text-iter instance. An iterator represents a position between two characters in the text buffer. The gtk:text-iter structure is a structure designed to be allocated on the stack. It is guaranteed to be copiable by value and never contain any heap-allocated data. Iterators are not valid indefinitely. Whenever the text buffer is modified in a way that affects the number of characters in the text buffer, all outstanding iterators become invalid. Note that deleting 5 characters and then reinserting 5 still invalidates iterators, though you end up with the same number of characters you pass through a state with a different number.

Because of this, iterators cannot be used to preserve positions across buffer modifications. To preserve a position, the gtk:text-mark object is ideal. You can think of a mark as an invisible cursor or insertion point. It floats in the text buffer, saving a position. If the text surrounding the mark is deleted, the mark remains in the position the text once occupied. If text is inserted at the mark, the mark ends up either to the left or to the right of the new text, depending on its gravity. The standard text cursor in left-to-right languages is a mark with right gravity, because it stays to the right of inserted text.

Like tags, marks can be either named or anonymous. There are two marks built-in to the gtk:text-buffer class. These are named "insert" and "selection_bound" and refer to the insertion point and the boundary of the selection which is not the insertion point, respectively. If no text is selected, these two marks will be in the same position. You can manipulate what is selected and where the cursor appears by moving these marks around. If you want to place the cursor in response to a user action, be sure to use the gtk:text-buffer-place-cursor function, which moves both at once without causing a temporary selection. Moving one then the other temporarily selects the range in between the old and new positions.

Text buffers always contain at least one line, but may be empty, that is, buffers can contain zero characters. The last line in the text buffer never ends in a line separator (such as newline). The other lines in the text buffer always end in a line separator. Line separators count as characters when computing character counts and character offsets. Note that some Unicode line separators are represented with multiple bytes in UTF-8, and the two-character sequence "\r\n" is also considered a line separator.

Simple Example
A simple usage of the gtk:text-view widget might look like this:
(defun do-text-view-simple (&optional application)
  (let* ((textview (make-instance 'gtk:text-view
                                  :wrap-mode :word
                                  :top-margin 6
                                  :top-bottom 6
                                  :left-margin 6
                                  :right-margin 6))
         (window (make-instance 'gtk:window
                                :application application
                                :child textview
                                :title "Simple Text View"
                                :default-width 350
                                :default-height 200))
         (buffer (gtk:text-view-buffer textview)))
    (g:signal-connect window "close-request"
        (lambda (widget)
          (declare (ignore widget))
          (let ((start (gtk:text-buffer-start-iter buffer))
                (end (gtk:text-buffer-end-iter buffer))
                (include-hidden-chars t))
            (print (gtk:text-buffer-get-text buffer
                                             start
                                             end
                                             include-hidden-chars))
            (terpri))))
    (setf (gtk:text-buffer-text buffer) *lorem-ipsum-short*)
    (gtk:window-present window)))      
In many cases it is also convenient to first create the text buffer with the gtk:text-buffer-new function, then create a text view for that text buffer with the gtk:text-view-new-with-buffer function. Or you can change the text buffer the text view displays after the text view is created with the gtk:text-view-buffer function.

Example of Changing Text Attributes
The way to affect text attributes in the gtk:text-view widget is to apply tags that change the attributes for a region of text. For text features that come from the theme - such as font and foreground color - use CSS to override their default values.
(defun do-text-view-attributes (&optional application)
  (let* ((textview (make-instance 'gtk:text-view
                                  ;; Change left margin throughout the widget
                                  :left-margin 24
                                  ;; Change top margin
                                  :top-margin 12))
         (window (make-instance 'gtk:window
                                :application application
                                :child textview
                                :title "Text View Attributes"
                                :default-width 350
                                :default-height 200))
         (provider (gtk:css-provider-new))
         (buffer (gtk:text-view-buffer textview)))
    (setf (gtk:text-buffer-text buffer) "Hello, this is some text.")
    ;; Load CSS from data into the provider and apply CSS
    (gtk:css-provider-load-from-data provider
                                     ".viewstyle textview {
                                        color : Green;
                                        font : 20px Purisa; }")
    (gtk:widget-add-css-class window "viewstyle")
    (gtk:widget-add-provider window provider)
    ;; Use a tag to change the color for just one part of the text view
    (let ((tag (gtk:text-buffer-create-tag buffer
                                           "blue_foreground"
                                           :foreground "blue"))
          (start (gtk:text-buffer-iter-at-offset buffer 7))
          (end (gtk:text-buffer-iter-at-offset buffer 12)))
      ;; Apply the tag to a region of the text in the buffer
      (gtk:text-buffer-apply-tag buffer tag start end))
    ;; Show the window
    (gtk:window-present window)))      
The GTK4 demo that comes with GTK contains more example code for the gtk:text-view widget.

GtkTextIter

GFlags gtk:text-search-flags
Declaration:
(gobject:define-gflags "GtkTextSearchFlags" text-search-flags
  (:export t
   :type-initializer "gtk_text_search_flags_get_type")
  (:visible-only 1)
  (:text-only 2)
  (:case-insensitive 4))  
Values:
:visible-only
Search only visible data. A search match may have invisible text interspersed.
:text-only
Search only text. A match may have pixbufs or child widgets mixed inside the matched range.
:case-insensitive
The text will be matched regardless of what case it is in.
Details:
Flags affecting how a search is done. If neither :visible-only nor :text-only are enabled, the match must be exact. The special 0xFFFC character will match embedded pixbufs or child widgets.
See also:
2024-7-1
GBoxed gtk:text-iter
Declaration:
(glib:define-gboxed-opaque text-iter "GtkTextIter"
  :export t
  :type-initializer "gtk_text_iter_get_type"
  :alloc (%text-iter-alloc))  
Returned by:
Details:
Most text manipulation is accomplished with iterators, represented by a gtk:text-iter instance. An iterator represents a position between two characters in the text buffer.

Iterators are not valid indefinitely. Whenever the text buffer is modified in a way that affects the number of characters in the text buffer, all outstanding iterators become invalid. Note that deleting 5 characters and then reinserting 5 characters still invalidates iterators, though you end up with the same number of characters you pass through a state with a different number.
See also:
2024-7-1
Function gtk:text-iter-new ()
Returns:
The newly allocated gtk:text-iter instance.
Details:
Returns a newly allocated iterator.
See also:
2024-7-1
Function gtk:text-iter-buffer (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The gtk:text-buffer object.
Details:
Returns the text buffer this iterator is associated with.
See also:
2024-7-1
Function gtk:text-iter-copy (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The newly allocated gtk:text-iter instance with the copy of iter.
Details:
Creates a copy of an iterator.
See also:
2024-6-24
Function gtk:text-iter-assign (iter other)
Arguments:
iter -- a gtk:text-iter instance
other -- another gtk:text-iter instance
Details:
Assigns the value of other to iter.
See also:
2024-7-1
Function gtk:text-iter-offset (iter)
Syntax:
(gtk:text-iter-offset iter) => offset
(setf (gtk:text-iter-offset iter) offset)
Arguments:
iter -- a gtk:text-iter instance
offset -- an integer with a character offset
Details:
The gtk:text-iter-offset function returns the character offset of an iterator. The (setf gtk:text-iter-offset) function sets the iterator to point to the given character offset.

Each character in a text buffer has an offset, starting with 0 for the first character in the text buffer. Use the gtk:text-buffer-iter-at-offset function to convert an character offset back into an iterator.
See also:
2024-7-1
Function gtk:text-iter-line (iter)
Syntax:
(gtk:text-iter-line iter) => line
(setf (gtk:text-iter-line iter) line)
Arguments:
iter -- a gtk:text-iter instance
line -- an integer with the line number, counted from 0
Details:
The gtk:text-iter-line function returns the line number containing the iterator. The (setf gtk:text-iter-line) function moves the iterator to the start of the given line number.

Lines in a text buffer are numbered beginning with 0 for the first line in the text buffer. If the given line number is negative or larger than the number of lines in the text buffer, moves the iterator to the start of the last line in the text buffer.
See also:
2024-7-1
Function gtk:text-iter-line-offset (iter &key visible)
Syntax:
(gtk:text-iter-line-offset iter) => offset
(gtk:text-iter-line-offset iter :visible t) => offset
(setf (gtk:text-iter-line-offset iter) offset)
(setf (gtk:text-iter-line-offset iter :visible t) offset)
Arguments:
iter -- a gtk:text-iter instance
offset -- an integer with a character offset relative to the start of the current line of the iterator
visible -- a boolean keyword argument, the default is false
Details:
The gtk:text-iter-line-offset function returns the character offset of the iterator, counting from the start of a newline-terminated line. The (setf gtk:text-iter-line-offset) function moves the iterator within a line, to the new character offset. If the visible keyword argument is true, the function does not count characters that are invisible due to tags with the invisible attribute toggled on.

The first character on the line has offset 0. The given character offset must be less than or equal to the number of characters in the line. If equal, the iterator moves to the start of the next line. See the gtk:text-iter-line-index function if you have a byte index rather than a character offset.
Notes:
This function combines the *_line_offset() and *_visible_line_offset() functions into one, using the visible keyword argument.
See also:
2024-7-26
Function gtk:text-iter-line-index (iter &key visible)
Syntax:
(gtk:text-iter-line-index iter) => index
(gtk:text-iter-line-index iter :visible t) => index
(setf (gtk:text-iter-line-offset iter) index)
(setf (gtk:text-iter-line-offset iter :visible t) index)
Arguments:
iter -- a gtk:text-iter instance
index -- an integer with a byte index relative to the start of the current line of the iterator
visible -- a boolean keyword argument, the default is false
Details:
The gtk:text-iter-line-index function returns the byte index of the iterator, counting from the start of a newline-terminated line. The (setf gtk:text-iter-line-index) function moves the iterator within a line, to the new byte index. If the visible keyword argument is true, the function does not count bytes that are invisible due to tags with the invisible attribute toggled on.

Remember that the text buffer encodes text in UTF-8, and that characters can require a variable number of bytes to represent. The given byte index must be at the start of a character, it cannot be in the middle of a UTF-8 encoded character.
Notes:
This function combines the *_line_index() and *_visible_line_index() functions into one, using the visible keyword argument.
See also:
2024-7-26
Function gtk:text-iter-char (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The Unicode character.
Details:
Returns a Unicode character at this iterator, or #\Nul if the iterator is not dereferenceable. If the element at this iterator is a non-character element, such as an image embedded in the text buffer, the Unicode #OBJECT_REPLACEMENT_CHARACTER character with the 0xFFFC char code is returned. If invoked on the end iterator, #\Nul with the 0 char code is returned.
See also:
2024-7-1
Function gtk:text-iter-slice (start end &key visible)
Arguments:
start -- a gtk:text-iter instance with the start of a range
end -- a gtk:text-iter instance with the end of a range
visible -- a boolean keyword argument, the default is false
Returns:
The string with a slice of text from the text buffer.
Details:
Returns a string with the text in the given range. If the visible keyword argument is true, invisible text is not included. Invisible text is usually invisible because a gtk:text-tag object with the invisible attribute turned on has been applied to it.

A "slice" is a string of characters encoded in UTF-8 format, including the Unicode "unknown" character 0xFFFC for iterable non-character elements in the text buffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned string will correspond to byte offsets in the text buffer. Note that the character 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget is in the text buffer.
See also:
2024-7-26
Function gtk:text-iter-text (start end &key visible)
Arguments:
start -- a gtk:text-iter instance with the start of a range
end -- a gtk:text-iter instance with the end of a range
visible -- a boolean keyword argument, the default is false
Returns:
The string with characters from the text buffer.
Details:
Returns a string with the text in the given range. If the visible keyword argument is true, invisible text is not included. Invisible text is usually invisible because a gtk:text-tag object with the invisible attribute turned on has been applied to it.

If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the text buffer. If you want offsets to correspond, see the gtk:text-iter-slice function.
See also:
2024-7-26
Function gtk:text-iter-paintable (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The gdk:paintable object at the iterator.
Details:
If the element at the iterator is a paintable, the paintable is returned. Otherwise, nil is returned.
See also:
2024-7-1
Function gtk:text-iter-marks (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
List of gtk:text-mark objects.
Details:
Returns a list of all text marks at this location. Because text marks are not iterable, they do not take up any "space" in the text buffer, they are just text marks in between iterable locations, multiple text marks can exist in the same place. The returned list is not in any meaningful order.
See also:
2024-7-1
Function gtk:text-iter-toggled-tags (iter toggled)
Arguments:
iter -- a gtk:text-iter instance
toggled -- true to get toggled-on tags
Returns:
The list of gtk:text-tag objects toggled at this point.
Details:
Returns a list of tags that are toggled on or off at this point.

If toggled is true, the list contains tags that are toggled on. If a tag is toggled on at the iterator, then some non-empty range of characters following the iterator has that tag applied to it. If a tag is toggled off, then some non-empty range following the iterator does not have the tag applied to it.
See also:
2024-7-1
Function gtk:text-iter-child-anchor (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The gtk:text-child-anchor object at the iterator.
Details:
If the location at the iterator contains an anchor, the anchor is returned. Otherwise, nil is returned.
See also:
2024-7-1
Function gtk:text-iter-starts-tag (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object, or nil
Returns:
True if the iterator is the start of a range tagged with tag.
Details:
Returns true if the tag is toggled on at exactly this point. If tag is nil, returns true if any tag is toggled on at this point.

Note that if the gtk:text-iter-starts-tag function returns true, it means that the iterator is at the beginning of the tagged range, and that the character at the iterator is inside the tagged range. In other words, unlike the gtk:text-iter-ends-tag function, if the gtk:text-iter-starts-tag function returns true, the gtk:text-iter-has-tag function will also return true for the same parameters.
See also:
2024-7-1
Function gtk:text-iter-ends-tag (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object, or nil
Returns:
True if the iterator is the end of a range tagged with tag.
Details:
Returns true if tag is toggled off at exactly this point. If tag is nil, returns true if any tag is toggled off at this point. Note that the gtk:text-iter-ends-tag function returns true if the iterator is the end of the tagged range. The gtk:text-iter-has-tag function tells you whether an iterator is within a tagged range.
See also:
2024-7-1
Function gtk:text-iter-toggles-tag (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object, or nil
Returns:
The boolean whether tag is toggled on or off at the iterator.
Details:
Tells you whether a range with tag applied to it begins or ends at the iterator. This is equivalent to
(or (gtk:text-iter-starts-tag iter tag)
    (gtk:text-iter-ends-tag iter tag))  
See also:
2024-7-1
Function gtk:text-iter-has-tag (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object
Returns:
True if the iterator is tagged with tag.
Details:
Returns true if the iterator is within a range tagged with tag.
See also:
2024-7-1
Function gtk:text-iter-tags (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
List of gtk:text-tag objects.
Details:
Returns a list of tags that apply to the iterator. The list is in ascending order of priority, highest-priority tags are last.
See also:
2024-7-1
Function gtk:text-iter-editable (iter setting)
Arguments:
iter -- a gtk:text-iter instance
setting -- true if text is editable by default
Returns:
True if the iterator is inside an editable range.
Details:
Returns whether the character at the iterator is within an editable region of text. Non-editable text is "locked" and cannot be changed by the user via the gtk:text-view widget. If no tags applied to this text affect editability, setting will be returned.

You do not want to use this function to decide whether text can be inserted at the iterator, because for insertion you do not want to know whether the char at the iterator is inside an editable range, you want to know whether a new character inserted at the iterator would be inside an editable range. Use the gtk:text-iter-can-insert function to handle this case.
See also:
2024-7-1
Function gtk:text-iter-can-insert (iter editable)
Arguments:
iter -- a gtk:text-iter instance
editabe -- true if text is editable by default
Returns:
True if the text inserted at the iterator would be editable.
Details:
Considering the default editability of the text buffer, and tags that affect editability, determines whether text inserted at the iterator would be editable.

If text inserted at the iterator would be editable then the user should be allowed to insert text at the iterator. The gtk:text-buffer-insert function with the true value for the interactive argument uses this function to decide whether insertions are allowed at a given position.
See also:
2024-7-1
Function gtk:text-iter-starts-word (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is at the start of a word.
Details:
Determines whether the iterator begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango word break algorithms.
See also:
2024-7-1
Function gtk:text-iter-ends-word (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is at the end of a word.
Details:
Determines whether the iterator ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango word break algorithms.
See also:
2024-7-1
Function gtk:text-iter-inside-word (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is inside a word.
Details:
Determines whether the iterator is inside a natural-language word, as opposed to say inside some whitespace. Word breaks are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango word break algorithms.
See also:
2024-7-1
Function gtk:text-iter-starts-line (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator begins a line.
Details:
Returns true if the iterator begins a paragraph, for example, if the gtk:text-iter-line-offset function would return 0. However this function is potentially more efficient than the gtk:text-iter-line-offset function because it does not have to compute the offset, it just has to see whether it is 0.
See also:
2024-7-1
Function gtk:text-iter-ends-line (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is at the end of a line.
Details:
Returns true if the iterator points to the start of the paragraph delimiter characters for a line. Delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character.

Note that an iterator pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end iterator is considered to be at the end of a line, even though there are no paragraph delimiter chars there.
See also:
2024-7-1
Function gtk:text-iter-starts-sentence (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is at the start of a sentence.
Details:
Determines whether the iterator begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango text boundary algorithms.
See also:
2024-7-1
Function gtk:text-iter-ends-sentence (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is at the end of a sentence.
Details:
Determines whether the iterator ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango text boundary algorithms.
See also:
2024-7-1
Function gtk:text-iter-inside-sentence (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is inside a sentence.
Details:
Determines whether the iterator is inside a sentence, as opposed to in between two sentences, for example, after a period and before the first letter of the next sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango text boundary algorithms.
See also:
2024-7-1
Function gtk:text-iter-is-cursor-position (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the cursor can be placed at the iterator.
Details:
See the gtk:text-iter-move function with the :cursor-position value for the by keyword argument, the pango:log-attr structure or the pango:default-break function for details on what a cursor position is.
See also:
gtk:text-iter
gtk:text-buffer
pango:log-attr
pango:default-break
gtk:text-iter-move
2024-7-1
Function gtk:text-iter-chars-in-line (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The integer with the number of characters in the line.
Details:
Returns the number of characters in the line containing the iterator, including the paragraph delimiters.
See also:
2024-7-1
Function gtk:text-iter-bytes-in-line (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The integer with the number of bytes in the line.
Details:
Returns the number of bytes in the line containing the iterator, including the paragraph delimiters.
See also:
2024-7-1
Function gtk:text-iter-language (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
The pange-language instance with the language in effect at the iterator.
Details:
Returns the language in effect at the iterator. If no tags affecting language apply to the iterator, the return value is identical to that of the gtk:default-language function.
See also:
2024-7-1
Function gtk:text-iter-is-end (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is the end iterator.
Details:
Returns true if the iterator is the end iterator, that is, one past the last dereferenceable iterator in the text buffer. The gtk:text-iter-is-end function is the most efficient way to check whether an iterator is the end iterator.
See also:
2024-7-1
Function gtk:text-iter-is-start (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if the iterator is the first in the text buffer.
Details:
Returns true if the iterator is the first iterator in the text buffer, that is if the iterator has a character offset of 0.
See also:
2024-7-1
Function gtk:text-iter-move (iter &key count by direction)
Arguments:
iter -- a gtk:text-iter instance
count -- an integer with the default value 1
by -- a keyword which determines the operation to perform, the default value is :char
direction -- a keyword for the direction, the default value is :forward
Details:
This is a convenience function of the Lisp implementation, which replaces the functions to move the iterator in the text buffer.

The following operations are performed depending on the by keyword argument:
:char
Moves count characters if possible in the given direction, which is :forward or :backward. If count would move past the start or end of the text buffer, moves to the start or end of the text buffer.

The return value indicates whether the new position of the iterator is different from its original position, and dereferenceable, the last iterator in the text buffer is not dereferenceable. If count is 0, the function does nothing and returns false.

This replaces the functions:
  • gtk_text_iter_forward_char()
  • gtk_text_iter_backward_char()
  • gtk_text_iter_forward_chars()
  • gtk_text_iter_backward_chars()
:line
Moves the iterator to the start of the next line for the :forward direction or to the start of the previous line for the :backward direction.

If the the iterator is already on the last line of the text buffer for a :forward direction, moves the iterator to the end of the current line. If after the operation, the iterator is at the end of the text buffer and not dereferencable, returns false. Otherwise, returns true.

For the :backward direction returns true if the iterator could be moved, for example, if the iterator was at character offset 0, this function returns false. Therefore if the iterator was already on line 0, but not at the start of the line, the iterator is snapped to the start of the line and the function returns true. Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.

This replaces the functions:
  • gtk_text_iter_forward_line()
  • gtk_text_iter_backward_line()
  • gtk_text_iter_forward_lines()
  • gtk_text_iter_backward_lines()
:word
Moves forward up to count times for the :forward direction to the next word end. If the iterator is currently on a word end, moves forward to the next one after that.

Moves backward up to count times for the :backward direction to the previous word start. If the iterator is currently on a word start, moves backward to the next one after that.

Word breaks are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango word break algorithms.

Returns true if the iterator moved and is not the end iterator.

This replaces the functions:
  • gtk_text_iter_forward_word_end()
  • gtk_text_iter_backward_word_start()
  • gtk_text_iter_forward_word_ends()
  • gtk_text_iter_backward_word_starts()
:cursor-position
Moves the iterator up to count cursor positions forward or backward.

Cursor positions are (unsurprisingly) positions where the cursor can appear. Perhaps surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered. So the cursor cannot go between those two characters. See also the pango:log-attr structure and the pango:default-break function.

Returns true if we moved and the new position is dereferenceable.

This replaces the functions:
  • gtk_text_iter_forward_cursor_position()
  • gtk_text_iter_backward_cursor_position()
  • gtk_text_iter_forward_cursor_positions()
  • gtk_text_iter_backward_cursor_positions()
:sentence
Moves backward to the previous sentence start or forward to the next sentence end. If the iterator is already at the start of a sentence, moves backward to the next one. If the iterator is at the end of a sentence, moves to the next end of sentence.

Sentence boundaries are determined by Pango and should be correct for nearly any language, if not, the correct fix would be to the Pango text boundary algorithms.

This replaces the functions:
  • gtk_text_iter_forward_sentence_end()
  • gtk_text_iter_backward_sentence_start()
  • gtk_text_iter_forward_sentences_ends()
  • gtk_text_iter_backward_sentence_starts()
:visible-word
Moves forward to the next visible word end or backward to the previous visible word start.

If the iterator is currently on a word start, moves backward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language. If not, the correct fix would be to the Pango word break algorithms.

This replaces the functions:
  • gtk_text_iter_forward_visible_word_end()
  • gtk_text_iter_backward_visible_word_start()
  • gtk_text_iter_forward_visible_word_ends()
  • gtk_text_iter_backward_visible_word_starts()
:visible-line
Moves the iterator to the start of the next visible line or to the start of the previous visible line.

The return value indicates whether the iterator moved onto a dereferenceable position. If the iterator did not move, or moved onto the end iterator, then false is returned. If count is 0, the function does nothing and returns false.

This replaces the functions:
  • gtk_text_iter_forward_visible_line()
  • gtk_text_iter_backward_visible_line()
  • gtk_text_iter_forward_visible_lines()
  • gtk_text_iter_backward_visible_lines()
:visible-cursor-position
Moves the iterator forward to the next visible cursor position or forward to the previous visible cursor position.

Returns true if we moved and the new position is dereferenceable.

This replaces the functions:
  • gtk_text_iter_forward_visible_cursor_position()
  • gtk_text_iter_backward_visible_cursor_position()
  • gtk_text_iter_forward_visible_cursor_positions()
  • gtk_text_iter_backward_visible_cursor_positions()
See also:
2024-7-1
Function gtk:text-iter-forward-to-end (iter)
Arguments:
iter -- a gtk:text-iter instance
Details:
Moves the iterator forward to the "end iterator", which points one past the last valid character in the text buffer. The gtk:text-iter-char function called on the end iterator returns #\Nul, which is convenient for writing loops.
See also:
2024-7-1
Function gtk:text-iter-forward-to-line-end (iter)
Arguments:
iter -- a gtk:text-iter instance
Returns:
True if we moved and the new location is not the end iterator.
Details:
Moves the iterator to point to the paragraph delimiter characters, which will be either a newline, a carriage return, a carriage return/newline in sequence, or the Unicode paragraph separator character.

If the iterator is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If the iterator is on the last line in the text buffer, which does not end in paragraph delimiters, moves to the end iterator (end of the last line), and returns false.
See also:
2024-7-1
Function gtk:text-iter-forward-to-tag-toggle (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object, or nil
Returns:
True if we found a tag toggle after the iterator.
Details:
Moves forward to the next toggle (on or off) of tag, or to the next toggle of any tag if tag is nil. If no matching tag toggles are found, returns false, otherwise true. Does not return toggles located at the iterator, only toggles after the iterator. Sets the iterator to the location of the toggle, or to the end of the text buffer if no toggle is found.
See also:
2024-7-1
Function gtk:text-iter-backward-to-tag-toggle (iter tag)
Arguments:
iter -- a gtk:text-iter instance
tag -- a gtk:text-tag object, or nil
Returns:
True if we found a tag toggle before the iterator.
Details:
Moves backward to the next toggle (on or off) of the tag, or to the next toggle of any tag if tag is nil. If no matching tag toggles are found, returns false, otherwise true. Does not return toggles located at the iterator, only toggles before the iterator. Sets the iterator to the location of the toggle, or the start of the text buffer if no toggle is found.
See also:
2024-7-1
Callback gtk:text-char-predicate
Syntax:
lambda (ch) => result
Arguments:
ch -- a Unichar character
result -- true if the character was found
Details:
A callback function used by the gtk:text-iter-find-char function to search a char in the text buffer.
See also:
2024-7-1
Function gtk:text-iter-find-char (iter predicate &key limit direction)
Arguments:
iter -- a gtk:text-iter instance
pred -- a gtk:text-char-predicate callback function to be called on each character
limit -- a gtk:text-iter instance with a search limit, or nil for none, the default is nil
direction -- a :forward value indicates forward search and a :backward value backward search, the default is :forward
Returns:
True if a match was found.
Details:
Advances the iterator, calling the pred function on each character. If direction is :backward goes backward from the iterator.

If the pred callback function returns true, returns true and stops scanning. If the pred callback function never returns true, the iterator is set to limit if limit is non-nil, otherwise to the end iterator. The limit keyword argument has the nil default value.
Notes:
This function combines the gtk_text_iter_forward_find_char() and gtk_text_iter_backward_find_char() functions into one single function using the direction keyword argument.
See also:
2024-7-1
Arguments:
iter -- a gtk:text-iter iterator with the start of the search
str -- a search string
flags -- a gtk:text-search-flags value with the flags affecting how the search is done
limit -- a gtk:text-iter iterator with the bound for the search, or nil for the end of the text buffer
direction -- a :forward value indicates forward search and a :backward value backward search, the default is :forward
Returns:
start -- a gtk:text-iter iterator with the start of the match
end -- a gtk:text-iter iterator with the end of the match
Details:
Searches for str in the text buffer that is associated with iter. The direction of the search is indicated with the direction keyword argument which has a :forward default value for forward search. For backward search the direction argument takes the :backward value. The flags and limit arguments are keyword arguments with a nil default value.

Any match is returned by returning start to the first character of the match and end to the first character after the match. The search will not continue past limit. Note that a search is a linear or O(n) operation, so you may wish to use limit to avoid locking up your UI on large text buffers.

The start value will never be set to an iterator located before iter, even if there is a possible end after or at iter.
Notes:
This function combines the gtk_text_iter_forward_search() and gtk_text_iter_backward_search() functions into one function.
See also:
2024-7-1
Function gtk:text-iter-equal (lhs rhs)
Arguments:
lhs -- a gtk:text-iter instance
rhs -- another gtk:text-iter instance
Returns:
True if the iterators point to the same place in the text buffer.
Details:
Tests whether two iterators are equal, using the fastest possible mechanism. This function is very fast. You can expect it to perform better than for example, getting the character offset for each iterator and comparing the offsets yourself. Also, it is a bit faster than the gtk:text-iter-compare function.
See also:
2024-7-1
Function gtk:text-iter-compare (lhs rhs)
Arguments:
lhs -- a gtk:text-iter instance
rhs -- another gtk:text-iter instance
Returns:
-1 if lhs is less than rhs, 1 if lhs is greater, 0 if they are equal.
Details:
A qsort()-style function that returns negative if lhs is less than rhs, positive if lhs is greater than rhs, and 0 if they are equal. Ordering is in character offset order, for example, the first character in the text buffer is less than the second character in the text buffer.
See also:
2024-7-1
Function gtk:text-iter-in-range (iter start end)
Arguments:
iter -- a gtk:text-iter instance
start -- a gtk:text-iter instance with the start of range
end -- a gtk:text-iter instance with the end of range
Returns:
True if the iterator is in the range.
Details:
Checks whether the iterator falls in the range [start, end). The start and end iterators must be in ascending order.
See also:
2024-7-1
Function gtk:text-iter-order (first second)
Arguments:
first -- a gtk:text-iter instance
second -- another gtk:text-iter instance
Details:
Swaps the value of first and second if second comes before first in the text buffer. That is, ensures that first and second are in sequence. Most text buffer functions that take a range call this automatically on your behalf, so there is no real reason to call it yourself in those cases. There are some exceptions, such as the gtk:text-iter-in-range functions, that expect a pre-sorted range.
See also:
2024-7-1

GtkTextTag

Class gtk:text-tag
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accumulative-margin
The accumulative-margin property of type :boolean (Read / Write)
Whether the margins accumulate or override each other. When set to true the margins of this tag are added to the margins of any other non-accumulative margins present. When set to false the margins override one another (the default).
Default value: false
allow-breaks
The allow-breaks property of type :boolean (Read / Write)
Whether breaks are allowed.
Default value: true
allow-breaks-set
The allow-breaks-set property of type :boolean (Read / Write)
Whether this tag affects line breaks.
Default value: false
background
The background property of type :string (Write)
The background color as a string.
Default value: nil
background-full-height
The background-full-height property of type :boolean (Read / Write)
Whether the background color fills the entire line height or only the height of the tagged characters.
Default value: false
background-full-height-set
The background-full-height-set property of type :boolean (Read / Write)
Whether this tag affects background height.
Default value: false
background-rgba
The background-rgba property of type gdk:rgba (Read / Write)
The background color.
background-set
The background-set property of type :boolean (Read / Write)
Whether this tag affects the background color.
Default value: false
direction
The direction property of type gtk:text-direction (Read / Write)
The text direction, for example, the :ltr value for left-to-right.
Default value: :none
editable
The editable property of type :boolean (Read / Write)
Whether the text can be modified by the user.
Default value: true
editable-set
The editable-set property of type :boolean (Read / Write)
Whether this tag affects text editability.
Default value: false
fallback
The fallback property of type :boolean (Read / Write)
Whether font fallback is enabled. When set to true, other fonts will be substituted where the current font is missing glyphs.
Default value: true
fallback-set
The fallback-set property of type :boolean (Read / Write)
Whether this tag affects font fallback.
Default value: false
family
The family property of type :string (Read / Write)
The name of the font family, for example, Sans, Helvetica, Times, Monospace.
Default value: nil
family-set
The family-set property of type :boolean (Read / Write)
Whether this tag affects the font family.
Default value: false
font
The font property of type :string (Read / Write)
The font description as string, for example, "Sans Italic 12". Note that the initial value of this property depends on the internals of the Pango font description.
Default value: nil
font-desc
The font-desc property of type pango:font-description (Read / Write)
The font description as a Pango font description.
font-features
The font-features property of type :string (Read / Write)
The OpenType font features, as a string.
Default value: nil
font-features-set
The font-features-set property of type :boolean (Read / Write)
Whether this tag affects font features.
Default value: false
foreground
The foreground property of type :string (Write)
The foreground color as a string.
Default value: nil
foreground-rgba
The foreground-rgba property of type gdk:rgba (Read / Write)
The foreground color.
foreground-set
The foreground-set property of type :boolean (Read / Write)
Whether this tag affects the foreground color.
Default value: false
indent
The indent property of type :int (Read / Write)
The amount to indent the paragraph, in pixels.
Default value: 0
indent-set
The indent-set property of type :boolean (Read / Write)
Whether this tag affects indentation.
Default value: false
insert-hyphens
The insert-hyphens property of type :boolean (Read / Write)
Whether to insert hyphens at breaks.
Default value: true
insert-hyphens-set
The insert-hyphens-set property of type :boolean (Read / Write)
Whether this tag affects insertion of hyphens.
Default value: false
invisible
The invisible property of type :boolean (Read / Write)
Whether this text is hidden. Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a text buffer containing invisible segments.
Default value: false
invisible-set
The invisible-set property of type :boolean (Read / Write)
Whether this tag affects text visibility.
Default value: false
justification
The justification property of type gtk:justification (Read / Write)
The left, right, or center justification.
Default value: :left
justification-set
The justification-set property of type :boolean (Read / Write)
Whether this tag affects paragraph justification.
Default value: false
language
The language property of type :string (Read / Write)
The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used. Note that the initial value of this property depends on the current locale, see also the gtk:default-language function.
Default value: nil
language-set
The language-set property of type :boolean (Read / Write)
Whether this tag affects the language the text is rendered as.
Default value: false
left-margin
The left-margin property of type :int (Read / Write)
The width of the left margin in pixels.
Allowed values: >= 0
Default value: 0
left-margin-set
The left-margin-set property of type :boolean (Read / Write)
Whether this tag affects the left margin.
Default value: false
letter-spacing
The letter-spacing property of type :int (Read / Write)
The extra spacing between graphemes, in Pango units.
Allowed values: >= 0
Default value: 0
letter-spacing-set
The letter-spacing-set property of type :boolean (Read / Write)
Whether this tag affects letter spacing.
Default value: false
line-height
The line-height property of type :float (Read / Write)
The factor to scale line height by. Since 4.6
line-height-set
The line-height-set property of type :boolean (Read / Write)
Whether this tag affects line height. Since 4.6
Default value: false
name
The name property of type :string (Read / Write / Construct)
The name used to refer to the text tag, nil for anonymous tags.
Default value: nil
overline
The overline property of type pango:overline (Read / Write)
The style of overline for this text.
Default value: :none
overline-rgba
The overline-rgba property of type gdk:rgba (Read / Write)
The color of overline for this text.
overline-rgba-set
The overline-rgba-set property of type :boolean (Read / Write)
Whether this tag affects overlining color.
Default value: false
overline-set
The overline-set property of type :boolean (Read / Write)
Whether this tag affects overlining.
Default value: false
paragraph-background
The paragraph-background property of type :string (Write)
The paragraph background color as a string.
Default value: nil
paragraph-background-rgba
The paragraph-background-rgba property of type gdk:rgba (Read / Write)
The paragraph background color.
paragraph-background-set
The paragraph-background-set property of type :boolean (Read / Write)
Whether this tag affects the paragraph background color.
Default value: false
pixels-above-lines
The pixels-above-lines property of type :int (Read / Write)
The pixels of blank space above paragraphs.
Allowed values: >= 0
Default value: 0
pixels-above-lines-set
The pixels-above-lines-set property of type :boolean (Read / Write)
Whether this tag affects the number of pixels above lines.
Default value: false
pixels-below-lines
The pixels-below-lines property of type :int (Read / Write)
The pixels of blank space below paragraphs.
Allowed values: >= 0
Default value: 0
pixels-below-lines-set
The pixels-below-lines-set property of type :boolean (Read / Write)
Whether this tag affects the number of pixels below lines.
Default value: false
pixels-inside-wrap
The pixels-inside-wrap property of type :int (Read / Write)
The pixels of blank space between wrapped lines in a paragraph.
Allowed values: >= 0
Default value: 0
pixels-inside-wrap-set
The pixels-inside-wrap-set property of type :boolean (Read / Write)
Whether this tag affects the number of pixels between wrapped lines.
Default value: false
right-margin
The right-margin property of type :int (Read / Write)
The width of the right margin in pixels.
Allowed values: >= 0
Default value: 0
right-margin-set
The right-margin-set property of type :boolean Read / Write)
Whether this tag affects the right margin.
Default value: false
rise
The rise property of type :int (Read / Write)
The offset of text above the baseline, below the baseline if rise is negative, in Pango units.
Default value: 0
rise-set
The rise-set property of type :boolean (Read / Write)
Whether this tag affects the rise.
Default value: false
scale
The scale property of type :double (Read / Write)
The font size as a scale factor relative to the default font size. This properly adapts to theme changes etc. so is recommended. Pango predefines some scales such as the pango:+scale-x-large+ value.
Allowed values: >= 0
Default value: 1
scale-set
The scale-set property of type :boolean (Read / Write)
Whether this tag scales the font size by a factor.
Default value: false
sentence
The sentence property of type :boolean (Read / Write)
Whether this tag represents a single sentence. This affects cursor movement. Since 4.6
Default value: false
sentence-set
The sentence-set property of type :boolean (Read / Write)
Whether this tag affects the sentence property. Since 4.6
Default value: false
show-spaces
The show-spaces property of type pango:show-flags (Read / Write)
How to render invisible characters.
show-spaces-set
The show-spaces-set property of type :boolean (Read / Write)
Whether this tag affects rendering of invisible characters.
Default value: false
size
The size property of type :int (Read / Write)
The font size in Pango units.
Allowed values: >= 0
Default value: 0
size-points
The size-points property of type :double (Read / Write)
The font size in points.
Allowed values: >= 0
Default value: 0
size-set
The size-set property of type :boolean (Read / Write)
Whether this tag affects the font size.
Default value: false
stretch
The stretch property of type pango:stretch (Read / Write)
The font stretch, for example, the :condensed value.
Default value: :normal
stretch-set
The stretch-set property of type :boolean (Read / Write)
Whether this tag affects the font stretch.
Default value: false
strikethrough
The strikethrough property of type :boolean (Read / Write)
Whether to strike through the text.
Default value: false
strikethrough-rgba
The strikethrough-rgba property of type gdk:rgba (Read / Write)
This property modifies the color of strikeouts. If not set, strikeouts will use the forground color.
strikethrough-rgba-set
The strikethrough-rgba-set property of type :boolean (Read / Write)
Whether the strikethrough-rgba property has been set.
Default value: false
strikethrough-set
The strikethrough-set property of type :boolean (Read / Write)
Whether this tag affects strikethrough.
Default value: false
style
The style property of type pango:style (Read / Write)
The font style, for example, the :italic value.
Default value: :normal
style-set
The style-set property of type :boolean (Read / Write)
Whether this tag affects the font style.
Default value: false
tabs
The tabs property of type pango:tab-array (Read / Write)
The custom tabs for this text.
tabs-set
The tabs-set property of type :boolean (Read / Write)
Whether this tag affects tabs.
Default value: false
text-transform
The text-transform property of type pango:text-transform (Read / Write)
How to transform the text for display. Since 4.6
Default value: :none
text-transform-set
The text-transform-set property of type :boolean (Read / Write)
Whether this tag affects the text-transform property. Since 4.6
Default value: false
underline
The underline property of type pango:underline (Read / Write)
The style of underline for this text.
Default value: :none
underline-rgba
The underline-rgba property of type gdk:rgba (Read / Write)
This property modifies the color of underlines. If not set, underlines will use the forground color. If the underline property is set to the :error value of the pango:underline enumeration, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults.
underline-rgba-set
The underline-rgba-set property of type :boolean (Read / Write)
Whether the underline-rgba property has been set.
Default value: false
underline-set
The underline-set property of type :boolean (Read / Write)
Whether this tag affects underlining.
Default value: false
variant
The variant property of type pango:variant (Read / Write)
The font variant, for example, the :small-caps value.
Default value: :normal
variant-set
The variant-set property of type :boolean (Read / Write)
Whether this tag affects the font variant.
Default value: false
weight
The weight property of type :int (Read / Write)
The font weight as an integer, see predefined values in the pango:weight enumeration, for example, the :bold value.
Allowed values: >= 0
Default value: 400
weight-set
The weight-set property of type :boolean (Read / Write)
Whether this tag affects the font weight.
Default value: false
word
The word property of type :boolean (Read / Write)
Whether this tag represents a single word. This affects line breaks and cursor movement. Since 4.6
word-set
The word-set property of type :boolean (Read / Write)
Whether this tag affects the word property. Since 4.6
Default value: false
wrap-mode
The wrap-mode property of type gtk:wrap-mode (Read / Write)
Whether to wrap lines never, at word boundaries, or at character boundaries.
Default value: :none
wrap-mode-set
The wrap-mode-set property of type :boolean (Read / Write)
Whether this tag affects line wrap mode.
Default value: false
Returned by:
Slot Access Functions:
Details:
A tag that can be applied to text contained in a gtk:text-buffer object. You may wish to begin by reading the text widget conceptual overview which gives an overview of all the objects and data types related to the text widget and how they work together.

Tags should be in the gtk:text-tag-table object for a given gtk:text-buffer object before using them with that text buffer. The gtk:text-buffer-create-tag function is the best way to create tags.

For each property of the gtk:text-tag class, there is a set property, for example, font-set corresponds to font. These set properties reflect whether a property has been set or not. They are maintained by GTK and you should not set them independently.
See also:
2024-7-2
Accessor gtk:text-tag-accumulative-margin (object)
Syntax:
(gtk:text-tag-accumulative-margin object) => setting
(setf (gtk:text-tag-accumulative-margin object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether the margins accumulate
Details:
Accessor of the accumulative-margin slot of the gtk:text-tag class. Whether the margins accumulate or override each other. When set to true the margins of this tag are added to the margins of any other non-accumulative margins present. When set to false the margins override one another, the default.
See also:
2024-7-2
Accessor gtk:text-tag-allow-breaks (object)
Syntax:
(gtk:text-tag-allow-breaks object) => setting
(setf (gtk:text-tag-allow-breaks object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether breaks are allowed
Details:
Accessor of the allow-breaks slot of the gtk:text-tag class. Whether breaks are allowed.
See also:
2024-7-2
Accessor gtk:text-tag-allow-breaks-set (object)
Syntax:
(gtk:text-tag-allow-breaks-set object) => setting
(setf (gtk:text-tag-allow-breaks-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects line breaks
Details:
Accessor of the allow-breaks-set slot of the gtk:text-tag class. Whether this tag affects line breaks.
See also:
2024-7-2
Accessor gtk:text-tag-background (object)
Syntax:
(setf (gtk:text-tag-background object) background)
Arguments:
object -- a gtk:text-tag object
background -- a string with the background color
Details:
Accessor of the background slot of the gtk:text-tag class.
Notes:
The background property is not readable, but writable.
(defvar tag (gtk:text-tag-new nil)) => TAG
(setf (gtk:text-tag-background tag) "red") => "red"
(gtk:text-tag-background-rgba tag)
=> #S(GDK:RGBA :RED 1.0 :GREEN 0.0 :BLUE 0.0 :ALPHA 1.0)    
See also:
2024-7-2
Accessor gtk:text-tag-background-full-height (object)
Syntax:
(gtk:text-tag-background-full-height object) => setting
(setf (gtk:text-tag-background-full-height object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether the background fills the entire line height
Details:
Accessor of the background-full-height slot of the gtk:text-tag class. Whether the background color fills the entire line height or only the height of the tagged characters.
See also:
2024-7-2
Accessor gtk:text-tag-background-full-height-set (object)
Syntax:
(gtk:text-tag-background-full-height-set object) => setting
(setf (gtk:text-tag-background-full-height-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects background height
Details:
Accessor of the background-full-height-set slot of the gtk:text-tag class. Whether this tag affects background height.
See also:
2024-7-2
Accessor gtk:text-tag-background-rgba (object)
Syntax:
(gtk:text-tag-background-rgba object) => color
(setf (gtk:text-tag-background-rgba object) color)
Arguments:
object -- a gtk:text-tag object
color -- a gdk:rgba color
Details:
Accessor of the background-rgba slot of the gtk:text-tag class. The background color.
See also:
2024-7-2
Accessor gtk:text-tag-background-set (object)
Syntax:
(gtk:text-tag-background-set object) => setting
(setf (gtk:text-tag-background-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the background color
Details:
Accessor of the background-set slot of the gtk:text-tag class. Whether this tag affects the background color.
See also:
2024-7-2
Accessor gtk:text-tag-direction (object)
Syntax:
(gtk:text-tag-direction object) => direction
(setf (gtk:text-tag-direction object) direction)
Arguments:
object -- a gtk:text-tag object
direction -- a gtk:text-direction value
Details:
Accessor of the direction slot of the gtk:text-tag class. The text direction.
See also:
2024-7-2
Accessor gtk:text-tag-editable (object)
Syntax:
(gtk:text-tag-editable object) => editable
(setf (gtk:text-tag-editable object) editable)
Arguments:
object -- a gtk:text-tag object
editable -- a boolean whether the text can be modified
Details:
Accessor of the editable slot of the gtk:text-tag class. Whether the text can be modified by the user.
See also:
2024-7-2
Accessor gtk:text-tag-editable-set (object)
Syntax:
(gtk:text-tag-editable-set object) => setting
(setf (gtk:text-tag-editable-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects text editability
Details:
Accessor of the editable-set slot of the gtk:text-tag class. Whether this tag affects text editability.
See also:
2024-7-2
Accessor gtk:text-tag-fallback (object)
Syntax:
(gtk:text-tag-fallback object) => fallback
(setf (gtk:text-tag-fallback object) fallback)
Arguments:
object -- a gtk:text-tag object
fallback -- a boolean whether font fallback is enabled
Details:
Accessor of the fallback slot of the gtk:text-tag class. Whether font fallback is enabled. When set to true, other fonts will be substituted where the current font is missing glyphs.
See also:
2024-7-2
Accessor gtk:text-tag-fallback-set (object)
Syntax:
(gtk:text-tag-fallback-set object) => setting
(setf (gtk:text-tag-fallback-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this affects font fallback
Details:
Accessor of the fallback-set slot of the gtk:text-tag class.
See also:
2024-7-2
Accessor gtk:text-tag-family (object)
Syntax:
(gtk:text-tag-family object) => family
(setf (gtk:text-tag-family object) family)
Arguments:
object -- a gtk:text-tag object
family -- a string with the name of the font family
Details:
Accessor of the family slot of the gtk:text-tag class. The name of the font family, for example, Sans, Helvetica, Times, Monospace.
See also:
2024-7-2
Accessor gtk:text-tag-family-set (object)
Syntax:
(gtk:text-tag-family-set object) => setting
(setf (gtk:text-tag-family-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the font family
Details:
Accessor of the family-set slot of the gtk:text-tag class. Whether this tag affects the font family.
See also:
2024-7-2
Accessor gtk:text-tag-font (object)
Syntax:
(gtk:text-tag-font object) => font
(setf (gtk:text-tag-font object) font)
Arguments:
object -- a gtk:text-tag object
font -- a string with a font description
Details:
Accessor of the font slot of the gtk:text-tag class. The font description as string, for example, "Sans Italic 12". Note that the initial value of this property depends on the internals of the pango:font-description structure.
See also:
2024-7-2
Accessor gtk:text-tag-font-desc (object)
Syntax:
(gtk:text-tag-font-desc object) => font-desc
(setf (gtk:text-tag-font object) font-desc)
Arguments:
object -- a gtk:text-tag object
font-desc -- a pango:font-description instance with a font description
Details:
Accessor of the font-desc slot of the gtk:text-tag class. The font description as a Pango font description.
See also:
2024-7-2
Accessor gtk:text-tag-font-features (object)
Syntax:
(gtk:text-tag-font-features object) => features
(setf (gtk:text-tag-font-features object) features)
Arguments:
object -- a gtk:text-tag object
features -- a string with the OpenType font features
Details:
Accessor of the font-features slot of the gtk:text-tag class. The OpenType font features, as a string.
See also:
2024-7-2
Accessor gtk:text-tag-font-features-set (object)
Syntax:
(gtk:text-tag-font-features-set object) => setting
(setf (gtk:text-tag-font-features-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects font features
Details:
Accessor of the font-features-set slot of the gtk:text-tag class. Whether this tag affects font features.
See also:
2024-7-2
Accessor gtk:text-tag-foreground (object)
Syntax:
(setf (gtk:text-tag-foreground object) color)
Arguments:
object -- a gtk:text-tag object
color -- a string with the foreground color
Details:
Accessor of the foreground slot of the gtk:text-tag class.
Notes:
The foreground property is not readable, but writable.
(defvar tag (gtk:text-tag-new nil)) => TAG
(setf (gtk:text-tag-foreground tag) "red") => "red"
(gtk:text-tag-foreground-rgba tag)
=> #S(GDK:RGBA :RED 1.0 :GREEN 0.0 :BLUE 0.0 :ALPHA 1.0)    
See also:
2024-7-2
Accessor gtk:text-tag-foreground-rgba (object)
Syntax:
(gtk:text-tag-foreground-rgba object) => color
(setf (gtk:text-tag-foreground-rgba object) color)
Arguments:
object -- a gtk:text-tag object
color -- a gdk:rgba color
Details:
Accessor of the foreground-rgba slot of the gtk:text-tag class. The foreground color.
See also:
2024-7-2
Accessor gtk:text-tag-foreground-set (object)
Syntax:
(gtk:text-tag-foreground-set object) => setting
(setf (gtk:text-tag-foreground-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tags affect the foreground color
Details:
Accessor of the foreground-set slot of the gtk:text-tag class. Whether this tag affects the foreground color.
See also:
2024-7-2
Accessor gtk:text-tag-indent (object)
Syntax:
(gtk:text-tag-indent object) => indent
(setf (gtk:text-tag-indent object) indent)
Arguments:
object -- a gtk:text-tag object
indent -- an integer with the amount to indent
Details:
Accessor of the indent slot of the gtk:text-tag class. The amount to indent the paragraph, in pixels.
See also:
2024-7-2
Accessor gtk:text-tag-indent-set (object)
Syntax:
(gtk:text-tag-indent-set object) => setting
(setf (gtk:text-tag-indent-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects indentation
Details:
Accessor of the indent-set slot of the gtk:text-tag class. Whether this tag affects indentation.
See also:
2024-7-2
Accessor gtk:text-tag-insert-hyphens (object)
Syntax:
(gtk:text-tag-insert-hyphens object) => setting
(setf (gtk:text-tag-insert-hyphens object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether to insert hyphens at breaks
Details:
Accessor of the insert-hyphens slot of the gtk:text-tag class. Whether to insert hyphens at breaks.
See also:
2024-7-2
Accessor gtk:text-tag-insert-hyphens-set (object)
Syntax:
(gtk:text-tag-insert-hyphens-set object) => setting
(setf (gtk:text-tag-insert-hyphens-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects insertion of hyphens
Details:
Accessor of the insert-hyphens-set slot of the gtk:text-tag class. Whether this tag affects insertion of hyphens.
See also:
2024-7-2
Accessor gtk:text-tag-invisible (object)
Syntax:
(gtk:text-tag-invisible object) => invisible
(setf (gtk:text-tag-invisible object) invisible)
Arguments:
object -- a gtk:text-tag object
invisible -- a boolean whether this text is hidden
Details:
Accessor of the invisible slot of the gtk:text-tag class. Whether this text is hidden. Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a text buffer containing invisible segments.
See also:
2024-7-2
Accessor gtk:text-tag-invisible-set (object)
Syntax:
(gtk:text-tag-invisible-set object) => setting
(setf (gtk:text-tag-invisible-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects visibility
Details:
Accessor of the invisible-set slot of the gtk:text-tag class. Whether this tag affects text visibility.
See also:
2024-7-2
Accessor gtk:text-tag-justification (object)
Syntax:
(gtk:text-tag-justification object) => justification
(setf (gtk:text-tag-justification object) justification)
Arguments:
object -- a gtk:text-tag object
justification -- a gtk:justification value
Details:
Accessor of the justification slot of the gtk:text-tag class. The left, right, or center justification.
See also:
2024-7-2
Accessor gtk:text-tag-justification-set (object)
Syntax:
(gtk:text-tag-justification-set object) => setting
(setf (gtk:text-tag-justification-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects paragraph justification
Details:
Accessor of the justification-set slot of the gtk:text-tag class. Whether this tag affects paragraph justification.
See also:
2024-7-2
Accessor gtk:text-tag-language (object)
Syntax:
(gtk:text-tag-language object) => language
(setf (gtk:text-tag-language object) language)
Arguments:
object -- a gtk:text-tag object
language -- a string with language this text is in
Details:
Accessor of the language slot of the gtk:text-tag class. The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used. Note that the initial value of this property depends on the current locale, see also the gtk:default-language function.
See also:
2024-7-2
Accessor gtk:text-tag-language-set (object)
Syntax:
(gtk:text-tag-language-set object) => setting
(setf (gtk:text-tag-language-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the language
Details:
Accessor of the language-set slot of the gtk:text-tag class. Whether this tag affects the language the text is rendered as.
See also:
2024-7-2
Accessor gtk:text-tag-left-margin (object)
Syntax:
(gtk:text-tag-left-margin object) => margin
(setf (gtk:text-tag-left-margin object) margin)
Arguments:
object -- a gtk:text-tag object
margin -- an integer with the width of the left margin in pixels
Details:
Accessor of the left-margin slot of the gtk:text-tag class. The width of the left margin in pixels.
See also:
2024-7-2
Accessor gtk:text-tag-left-margin-set (object)
Syntax:
(gtk:text-tag-left-margin-set object) => setting
(setf (gtk:text-tag-left-margin-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the left margin
Details:
Accessor of the left-margin-set slot of the gtk:text-tag class. Whether this tag affects the left margin.
See also:
2024-7-2
Accessor gtk:text-tag-letter-spacing (object)
Syntax:
(gtk:text-tag-letter-spacing object) => spacing
(setf (gtk:text-tag-letter-spacing object) spacing)
Arguments:
object -- a gtk:text-tag object
spacing -- an integer with extra spacing between graphems in Pango units
Details:
Accessor of the letter-spacing slot of the gtk:text-tag class. The extra spacing between graphemes, in Pango units.
See also:
2024-7-2
Accessor gtk:text-tag-letter-spacing-set (object)
Syntax:
(gtk:text-tag-letter-spacing-set object) => setting
(setf (gtk:text-tag-letter-spacing-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects letter spacing
Details:
Accessor of the letter-spacing-set slot of the gtk:text-tag class. Whether this tag affects letter spacing.
See also:
2024-7-2
Accessor gtk:text-tag-line-height (object)
Syntax:
(gtk:text-tag-line-height object) => height
(setf (gtk:text-tag-line-height object) height)
Arguments:
object -- a gtk:text-tag object
height -- a float with the factor to scale line height by
Details:
Accessor of the line-height slot of the gtk:text-tag class. The factor to scale line height by.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-line-height-set (object)
Syntax:
(gtk:text-tag-line-height-set object) => setting
(setf (gtk:text-tag-line-height-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects line height
Details:
Accessor of the line-height-set slot of the gtk:text-tag class. Whether this tag affects line height.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-name (object)
Syntax:
(gtk:text-tag-name object) => name
Arguments:
object -- a gtk:text-tag object
name -- a string with the name of the text tag
Details:
Accessor of the name slot of the gtk:text-tag class. The name used to refer to the text tag, nil for anonymous tags.
See also:
2024-7-2
Accessor gtk:text-tag-overline (object)
Syntax:
(gtk:text-tag-overline object) => setting
(setf (gtk:text-tag-overline object) setting
Arguments:
object -- a gtk:text-tag object
setting -- a pango:overline value
Details:
Accessor of the overline slot of the gtk:text-tag class. The style of overline for this text.
See also:
2024-7-2
Accessor gtk:text-tag-overline-rgba (object)
Syntax:
(gtk:text-tag-overline-rgba object) => rgba
(setf (gtk:text-tag-overline-rgba object) rgba
Arguments:
object -- a gtk:text-tag object
rgba -- a gdk:rgba instance with the color
Details:
Accessor of the overline-rgba slot of the gtk:text-tag class. The color of overline for this text.
See also:
2024-7-2
Accessor gtk:text-tag-overline-rgba-set (object)
Syntax:
(gtk:text-tag-overline-rgba-set object) => setting
(setf (gtk:text-tag-overline-rgba-set object) setting
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects overlining color
Details:
Accessor of the overline-rgba-set slot of the gtk:text-tag class. Whether this tag affects overlining color.
See also:
2024-7-2
Accessor gtk:text-tag-overline-set (object)
Syntax:
(gtk:text-tag-overline-set object) => setting
(setf (gtk:text-tag-overline-set object) setting
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects overlining
Details:
Accessor of the overline-set slot of the gtk:text-tag class. Whether this tag affects overlining.
See also:
2024-7-2
Accessor gtk:text-tag-paragraph-background (object)
Syntax:
(gtk:text-tag-paragraph-background object) => color
(setf (gtk:text-tag-paragraph-background object) color)
Arguments:
object -- a gtk:text-tag object
color -- a string with the paragraph background color
Details:
Accessor of the paragraph-background slot of the gtk:text-tag class. The paragraph background color as a string.
See also:
2024-7-2
Accessor gtk:text-tag-paragraph-background-rgba (object)
Syntax:
(gtk:text-tag-paragraph-background-rgba object) => color
(setf (gtk:text-tag-paragraph-background-rgba object) color)
Arguments:
object -- a gtk:text-tag object
color -- a gdk:rgba color
Details:
Accessor of the paragraph-background-rgba slot of the gtk:text-tag class. The paragraph background color.
See also:
2024-7-2
Accessor gtk:text-tag-paragraph-background-set (object)
Syntax:
(gtk:text-tag-paragraph-background-set object) => setting
(setf (gtk:text-tag-paragraph-background-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this affects the paragraph background color
Details:
Accessor of the paragraph-background-set slot of the gtk:text-tag class. Whether this tag affects the paragraph background color.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-above-lines (object)
Syntax:
(gtk:text-tag-pixels-above-lines object) => pixels
(setf (gtk:text-tag-pixels-above-lines object) pixels)
Arguments:
object -- a gtk:text-tag object
pixels -- an integer with the pixels of blank space above paragraphs
Details:
Accessor of the pixels-above-lines slot of the gtk:text-tag class. The pixels of blank space above paragraphs.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-above-lines-set (object)
Syntax:
(gtk:text-tag-pixels-above-lines-set object) => setting
(setf (gtk:text-tag-pixels-above-lines-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the number of pixels above lines
Details:
Accessor of the pixels-above-lines-set slot of the gtk:text-tag class. Whether this tag affects the number of pixels above lines.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-below-lines (object)
Syntax:
(gtk:text-tag-pixels-below-lines object) => pixels
(setf (gtk:text-tag-pixels-below-lines object) pixels)
Arguments:
object -- a gtk:text-tag object
pixels -- an integer with the pixels of blank space below paragraphs
Details:
Accessor of the pixels-below-lines slot of the gtk:text-tag class. Pixels of blank space below paragraphs.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-below-lines-set (object)
Syntax:
(gtk:text-tag-pixels-below-lines-set object) => setting
(setf (gtk:text-tag-pixels-below-lines-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the number of pixels below lines
Details:
Accessor of the pixels-below-lines-set slot of the gtk:text-tag class. Whether this tag affects the number of pixels below lines.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-inside-wrap (object)
Syntax:
(gtk:text-tag-pixels-inside-wrap object) => pixels
(setf (gtk:text-tag-pixels-inside-wrap object) pixels)
Arguments:
object -- a gtk:text-tag object
pixels -- an integer with the pixels of blank space between wrapped lines in a paragraph
Details:
Accessor of the pixels-inside-wrap slot of the gtk:text-tag class. The pixels of blank space between wrapped lines in a paragraph.
See also:
2024-7-2
Accessor gtk:text-tag-pixels-inside-wrap-set (object)
Syntax:
(gtk:text-tag-pixels-inside-wrap-set object) => setting
(setf (gtk:text-tag-pixels-inside-wrap-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the number of pixels between wrapped lines
Details:
Accessor of the pixels-inside-wrap-set slot of the gtk:text-tag class. Whether this tag affects the number of pixels between wrapped lines.
See also:
2024-7-2
Accessor gtk:text-tag-right-margin (object)
Syntax:
(gtk:text-tag-right-margin object) => margin
(setf (gtk:text-tag-right-margin object) margin)
Arguments:
object -- a gtk:text-tag object
margin -- an integer with the right margin in pixels
Details:
Accessor of the right-margin slot of the gtk:text-tag class. The width of the right margin in pixels.
See also:
2024-7-2
Accessor gtk:text-tag-right-margin-set (object)
Syntax:
(gtk:text-tag-right-margin-set object) => setting
(setf (gtk:text-tag-right-margin-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the right margin
Details:
Accessor of the right-margin-set slot of the gtk:text-tag class. Whether this tag affects the right margin.
See also:
2024-7-2
Accessor gtk:text-tag-rise (object)
Syntax:
(gtk:text-tag-rise object) => rise
(setf (gtk:text-tag-rise object) rise)
Arguments:
object -- a gtk:text-tag object
rise -- an integer with the offset of text above the baseline in Pango units
Details:
Accessor of the rise slot of the gtk:text-tag class. The offset of text above the baseline, below the baseline if rise is negative, in Pango units.
See also:
2024-7-2
Accessor gtk:text-tag-rise-set (object)
Syntax:
(gtk:text-tag-rise-set object) => setting
(setf (gtk:text-tag-rise-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the rise
Details:
Accessor of the rise-set slot of the gtk:text-tag class. Whether this tag affects the rise.
See also:
2024-7-2
Accessor gtk:text-tag-scale (object)
Syntax:
(gtk:text-tag-scale object) => scale
(setf (gtk:text-tag-scale object) scale)
Arguments:
object -- a gtk:text-tag object
scale -- a double float with the font size as a scale factor
Details:
Accessor of the scale slot of the gtk:text-tag class. The font size as a scale factor relative to the default font size. This property adapts to theme changes etc. so is recommended. Pango predefines some scales such as the pango:+scale-x-large+ value.
See also:
2024-7-2
Accessor gtk:text-tag-scale-set (object)
Syntax:
(gtk:text-tag-scale-set object) => setting
(setf (gtk:text-tag-scale-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag scales the font size
Details:
Accessor of the scale-set slot of the gtk:text-tag class. Whether this tag scales the font size by a factor.
See also:
2024-7-2
Accessor gtk:text-tag-sentence (object)
Syntax:
(gtk:text-tag-sentence object) => setting
(setf (gtk:text-tag-sentence object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag represents a single sentence
Details:
Accessor of the sentence slot of the gtk:text-tag class. Whether this tag represents a single sentence. This affects cursor movement.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-sentence-set (object)
Syntax:
(gtk:text-tag-sentence-set object) => setting
(setf (gtk:text-tag-sentence-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the sentence property.
Details:
Accessor of the sentence-set slot of the gtk:text-tag class. Whether this tag affects the sentence property.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-show-spaces (object)
Syntax:
(gtk:text-tag-show-spaces object) => setting
(setf (gtk:text-tag-show-spaces object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a pango:show-flags value
Details:
Accessor of the show-spaces slot of the gtk:text-tag class. How to render invisible characters.
See also:
2024-7-2
Accessor gtk:text-tag-show-spaces-set (object)
Syntax:
(gtk:text-tag-show-spaces-set object) => setting
(setf (gtk:text-tag-show-spaces-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects rendering of invisible characters
Details:
Accessor of the show-spaces-set slot of the gtk:text-tag class. Whether this tag affects rendering of invisible characters.
See also:
2024-7-2
Accessor gtk:text-tag-size (object)
Syntax:
(gtk:text-tag-size object) => size
(setf (gtk:text-tag-size object) size)
Arguments:
object -- a gtk:text-tag object
size -- an integer with the the font size in Pango units
Details:
Accessor of the size slot of the gtk:text-tag class. The font size in Pango units.
See also:
2024-7-2
Accessor gtk:text-tag-size-points (object)
Syntax:
(gtk:text-tag-size-points object) => size
(setf (gtk:text-tag-size-points object) size)
Arguments:
object -- a gtk:text-tag object
size -- a double float with the the font size in points
Details:
Accessor of the size-points slot of the gtk:text-tag class. The font size in points.
See also:
2024-7-2
Accessor gtk:text-tag-size-set (object)
Syntax:
(gtk:text-tag-size-set object) => setting
(setf (gtk:text-tag-size-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the font size
Details:
Accessor of the size-set slot of the gtk:text-tag class. Whether this tag affects the font size.
See also:
2024-7-2
Accessor gtk:text-tag-stretch (object)
Syntax:
(gtk:text-tag-stretch object) => stretch
(setf (gtk:text-tag-stretch object) stretch)
Arguments:
object -- a gtk:text-tag object
stretch -- a pango:stretch value
Details:
Accessor of the stretch slot of the gtk:text-tag class. The font stretch as a value of the pango:stretch enumeration, for example, the :condensed value.
See also:
2024-7-2
Accessor gtk:text-tag-stretch-set (object)
Syntax:
(gtk:text-tag-stretch-set object) => setting
(setf (gtk:text-tag-stretch-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag afects the font stretch
Details:
Accessor of the stretch-set slot of the gtk:text-tag class. Whether this tag affects the font stretch.
See also:
2024-7-2
Accessor gtk:text-tag-strikethrough (object)
Syntax:
(gtk:text-tag-strikethrough object) => strikethrough
(setf (gtk:text-tag-strikethrough object) strikethrough)
Arguments:
object -- a gtk:text-tag object
strikethrough -- a boolean whether to strike through the text
Details:
Accessor of the strikethrough slot of the gtk:text-tag class. Whether to strike through the text.
See also:
2024-7-2
Accessor gtk:text-tag-strikethrough-rgba (object)
Syntax:
(gtk:text-tag-strikethrough-rgba object) => color
(setf (gtk:text-tag-strikethrough-rgba object) color)
Arguments:
object -- a gtk:text-tag object
color -- a gdk:rgba instance with the color
Details:
Accessor of the strikethrough-rgba slot of the gtk:text-tag class. This property modifies the color of strikeouts. If not set, strikeouts will use the forground color.
See also:
2024-7-2
Accessor gtk:text-tag-strikethrough-rgba-set (object)
Syntax:
(gtk:text-tag-strikethrough-rgba-set object) => setting
(setf (gtk:text-tag-strikethrough-rgba-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether a strikethrough-rgba property has been set
Details:
Accessor of the strikethrough-rgba-set slot of the gtk:text-tag class. Whether the strikethrough-rgba property has been set.
See also:
2024-7-2
Accessor gtk:text-tag-strikethrough-set (object)
Syntax:
(gtk:text-tag-strikethrough-set object) => setting
(setf (gtk:text-tag-strikethrough-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects strikethrough
Details:
Accessor of the strikethrough-set slot of the gtk:text-tag class. Whether this tag affects strikethrough.
See also:
2024-7-2
Accessor gtk:text-tag-style (object)
Syntax:
(gtk:text-tag-style object) => style
(setf (gtk:text-tag-style object) style)
Arguments:
object -- a gtk:text-tag object
style -- a pango:style value
Details:
Accessor of the style slot of the gtk:text-tag class. The font style as a value of the pango:style enumeration, for example, the :italic value.
See also:
2024-7-2
Accessor gtk:text-tag-style-set (object)
Syntax:
(gtk:text-tag-style-set object) => setting
(setf (gtk:text-tag-style-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the font style
Details:
Accessor of the style-set slot of the gtk:text-tag class. Whether this tag affects the font style.
See also:
2024-7-2
Accessor gtk:text-tag-tabs (object)
Syntax:
(gtk:text-tag-tabs object) => tabs
(setf (gtk:text-tag-tabs object) tabs)
Arguments:
object -- a gtk:text-tag object
tabs -- a pango:tab-array instance with the custom tabs
Details:
Accessor of the tabs slot of the gtk:text-tag class. The custom tabs for this text.
See also:
2024-7-2
Accessor gtk:text-tag-tabs-set (object)
Syntax:
(gtk:text-tag-tabs-set object) => setting
(setf (gtk:text-tag-tabs-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this affects tabs
Details:
Accessor of the tabs-set slot of the gtk:text-tag class. Whether this tag affects tabs.
See also:
2024-7-2
Accessor gtk:text-tag-text-transform (object)
Syntax:
(gtk:text-tag-text-transform object) => transform
(setf (gtk:text-tag-text-transform object) transform)
Arguments:
object -- a gtk:text-tag object
transform -- a pango:text-transform value
Details:
Accessor of the text-transform slot of the gtk:text-tag class. How to transform the text for display.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-text-transform-set (object)
Syntax:
(gtk:text-tag-text-transform-set object) => setting
(setf (gtk:text-tag-text-transform-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the text-transform property.
Details:
Accessor of the text-transform-set slot of the gtk:text-tag class. Whether this tag affects the text-transform property.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-underline (object)
Syntax:
(gtk:text-tag-underline object) => underline
(setf (gtk:text-tag-underline object) underline)
Arguments:
object -- a gtk:text-tag object
underline -- a pango:underline value
Details:
Accessor of the underline slot of the gtk:text-tag class. The style of underline for this text.
See also:
2024-7-2
Accessor gtk:text-tag-underline-rgba (object)
Syntax:
(gtk:text-tag-underline-rgba object) => color
(setf (gtk:text-tag-underline-rgba object) color)
Arguments:
object -- a gtk:text-tag object
color -- a gdk:rgba instance with the color
Details:
Accessor of the underline-rgba slot of the gtk:text-tag class. This property modifies the color of underlines. If not set, underlines will use the forground color. If the underline property is set to the :error value of the pango:underline enumeration, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults.
See also:
2024-7-2
Accessor gtk:text-tag-underline-rgba-set (object)
Syntax:
(gtk:text-tag-underline-rgba-set object) => setting
(setf (gtk:text-tag-underline-rgba-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether the underline-rgba property has been set
Details:
Accessor of the underline-rgba-set slot of the gtk:text-tag class. Whether the underline-rgba property has been set.
See also:
2024-7-2
Accessor gtk:text-tag-underline-set (object)
Syntax:
(gtk:text-tag-underline-set object) => setting
(setf (gtk:text-tag-underline-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects underlining
Details:
Accessor of the underline-set slot of the gtk:text-tag class. Whether this tag affects underlining.
See also:
2024-7-2
Accessor gtk:text-tag-variant (object)
Syntax:
(gtk:text-tag-variant object) => variant
(setf (gtk:text-tag-variant object) variant)
Arguments:
object -- a gtk:text-tag object
variant -- a pango:variant value
Details:
Accessor of the variant slot of the gtk:text-tag class. The font variant as a value of the pango:variant enumeration, for example, the :small-caps value.
See also:
2024-7-2
Accessor gtk:text-tag-variant-set (object)
Syntax:
(gtk:text-tag-variant-set object) => setting
(setf (gtk:text-tag-variant-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this affects the font variant
Details:
Accessor of the variant-set slot of the gtk:text-tag class. Whether this tag affects the font variant.
See also:
2024-7-2
Accessor gtk:text-tag-weight (object)
Syntax:
(gtk:text-tag-weight object) => weight
(setf (gtk:text-tag-weight object) weight)
Arguments:
object -- a gtk:text-tag object
weight -- an integer for the font weight
Details:
Accessor of the weight slot of the gtk:text-tag class. The font weight as an integer, see predefined values in the pango:weight enumeration, for example, the :bold value.
See also:
2024-7-2
Accessor gtk:text-tag-weight-set (object)
Syntax:
(gtk:text-tag-weight-set object) => setting
(setf (gtk:text-tag-weight-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the font weight
Details:
Accessor of the weight-set slot of the gtk:text-tag class. Whether this tag affects the font weight.
See also:
2024-7-2
Accessor gtk:text-tag-word (object)
Syntax:
(gtk:text-tag-word object) => setting
(setf (gtk:text-tag-word object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag represents a single word
Details:
Accessor of the word slot of the gtk:text-tag class. Whether this tag represents a single word. This affects line breaks and cursor movement.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-word-set (object)
Syntax:
(gtk:text-tag-word-set object) => setting
(setf (gtk:text-tag-word-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects the word property.
Details:
Accessor of the word-set slot of the gtk:text-tag class. Whether this tag affects the word property.

Since 4.6
See also:
2024-7-2
Accessor gtk:text-tag-wrap-mode (object)
Syntax:
(gtk:text-tag-wrap-mode object) => mode
(setf (gtk:text-tag-wrap-mode object) mode)
Arguments:
object -- a gtk:text-tag object
mode -- a gtk:wrap-mode value
Details:
Accessor of the wrap-mode slot of the gtk:text-tag class. Whether to wrap lines never, at word boundaries, or at character boundaries.
See also:
2024-7-2
Accessor gtk:text-tag-wrap-mode-set (object)
Syntax:
(gtk:text-tag-wrap-mode-set object) => setting
(setf (gtk:text-tag-wrap-mode-set object) setting)
Arguments:
object -- a gtk:text-tag object
setting -- a boolean whether this tag affects line wrap mode
Details:
Accessor of the wrap-mode-set slot of the gtk:text-tag class. Whether this tag affects line wrap mode.
See also:
2024-7-2
Function gtk:text-tag-new (name &rest args)
Arguments:
name -- a string with the tag name, or nil
args -- list of property keywords and values
Returns:
The new gtk:text-tag object.
Details:
Creates a new tag.
Examples:
Create a tag with name "font-italic":
(gtk:text-tag-new "font-italic" :font "fixed" :style :italic)
=> #<gtk:text-tag {1006C86E63}>    
See also:
2024-7-2
Function gtk:text-tag-priority (tag)
Syntax:
(gtk:text-tag-priority tag) => priority
(setf (gtk:text-tag-priority tag) priority)
Arguments:
tag -- a gtk:text-tag object
priority -- an integer with the priority of the tag
Details:
The gtk:text-tag-priority function gets the tag priority. The (setf gtk:text-tag-priority) function sets the priority.

Valid priorities start at 0 and go to one less than the value of the result of the gtk:text-tag-table-size function. Each tag in a gtk:text-tag-table object has a unique priority. Setting the priority of one tag shifts the priorities of all the other tags in the tag table to maintain a unique priority for each tag. Higher priority tags "win" if two tags both set the same text attribute. When adding a tag to a tag table, it will be assigned the highest priority in the tag table by default. So normally the precedence of a set of tags is the order in which they were added to the tag table, or created with the gtk:text-buffer-create-tag function, which adds the tag to the tag table of the text buffer automatically.
See also:
2024-10-26
Function gtk:text-tag-changed (tag changed)
Arguments:
tag -- a gtk:text-tag object
changed -- a boolean whether the change affects the gtk:text-view layout
Details:
Emits the "tag-changed" signal on the gtk:text-tag-table object where the tag is included. The signal is already emitted when setting a gtk:text-tag property.
See also:
2024-7-2

GtkTextTagTable

Class gtk:text-tag-table
Superclasses:
gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A tag table defines a set of tags that can be used together. Each tag is stored in a gtk:text-tag-table object. Each text buffer has one tag table associated with it. Only tags from that tag table can be used with the text buffer. A single tag table can be shared between multiple text buffers, however.
GtkTextTagTable as GtkBuildable:
The gtk:text-tag-table implementation of the gtk:buildable interface supports adding tags by specifying "tag" as the type attribute of a <child> element.

Example: A UI definition fragment specifying tags.
<object class="GtkTextTagTable">
 <child type="tag">
   <object class="GtkTextTag"/>
 </child>
</object>    
Signal Details:
The "tag-added" signal
lambda (table tag)    :run-last      
table
The gtk:text-tag-table object which received the signal.
tag
The added gtk:text-tag object.
The "tag-changed" signal
lambda (table tag changed)    :run-last      
table
The gtk:text-tag-table object which received the signal.
tag
The changed gtk:text-tag object.
changed
The boolean whether the size has been changed.
The "tag-removed" signal
lambda (table tag)    :run-last      
table
The gtk:text-tag-table object which received the signal.
tag
The removed gtk:text-tag object.
See also:
2024-7-2
Function gtk:text-tag-table-new ()
Returns:
The new gtk:text-tag-table object.
Details:
Creates a new tag table. The tag table contains no tags by default.
See also:
2024-7-2
Function gtk:text-tag-table-add (table tag)
Arguments:
table -- a gtk:text-tag-table object
tag -- a gtk:text-tag object
Returns:
True on success.
Details:
Adds a tag to the tag table. The tag is assigned the highest priority in the tag table. The tag must not be in a tag table already, and may not have the same name as an already added tag.
See also:
2024-7-2
Function gtk:text-tag-table-remove (table tag)
Arguments:
table -- a gtk:text-tag-table object
tag -- a gtk:text-tag object
Details:
Remove a tag from the tag table. This will remove the reference of the tag table to the tag, so be careful - the tag will end up destroyed if you do not have a reference to it.
See also:
2024-7-2
Function gtk:text-tag-table-lookup (table name)
Arguments:
table -- a gtk:text-tag-table object
name -- a string with the name of a tag
Returns:
The gtk:text-tag object, or nil if none by that name is in the tag table.
Details:
Look up a named tag in the tag table.
See also:
2024-7-2
Callback gtk:text-tag-table-foreach-func
Syntax:
lambda (tag)
Arguments:
tag -- a gtk:text-tag object
Details:
The type of callback function passed to the gtk:text-tag-table-foreach function.
See also:
2024-7-2
Function gtk:text-tag-table-foreach (table func)
Arguments:
table -- a gtk:text-tag-table object
func -- a gtk:text-tag-table-foreach-func callback function to call on each tag
Details:
Calls func on each tag in the tag table. Note that the tag table may not be modified while iterating over it, you cannot add or remove tags.
See also:
2024-7-2
Function gtk:text-tag-table-size (table)
Arguments:
table -- a gtk:text-tag-table object
Returns:
The integer with the number of tags in table.
Details:
Returns the number of tags in the tag table.
See also:
2024-7-2

GtkTextMark

Class gtk:text-mark
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
left-gravity
The left-gravity property of type :boolean (Read / Write / Construct only)
Whether the text mark has left gravity.
Default value: false
name
The name property of type :string (Read / Write / Construct only)
The name of the text mark.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:text-mark object is like a bookmark in a text buffer. It preserves a position in the text buffer. You can convert the text mark to an iterator using the gtk:text-buffer-iter-at-mark function. Unlike iterators, text marks remain valid across buffer mutations, because their behavior is defined when text is inserted or deleted. When text containing a text mark is deleted, the text mark remains in the position originally occupied by the deleted text. When text is inserted at a text mark, a text mark with left gravity will be moved to the beginning of the newly inserted text, and a text mark with right gravity will be moved to the end.

Note that "left" and "right" here refer to logical direction. Left is toward the start of the buffer. In some languages such as Hebrew the logically leftmost text is not actually on the left when displayed.

Text marks are reference counted, but the reference count only controls the validity of the memory. Text marks can be deleted from the buffer at any time with the gtk:text-buffer-delete-mark function. Once deleted from the buffer, a text mark is essentially useless.

Text marks optionally have names. These can be convenient to avoid passing the gtk:text-mark object around. Text marks are typically created using the gtk:text-buffer-create-mark function.
See also:
2024-7-2
Accessor gtk:text-mark-left-gravity (object)
Syntax:
(gtk:text-mark-left-gravity object) => gravity
Arguments:
object -- a gtk:text-mark object
gravity -- true if the text mark has left gravity
Details:
Accessor of the left-gravity slot of the gtk:text-mark class. The gtk:text-mark-left-gravity function determines whether the text mark has left gravity. When text is inserted at the current location of the text mark, if the text mark has left gravity it will be moved to the left of the newly-inserted text, otherwise to the right.
See also:
2024-7-2
Accessor gtk:text-mark-name (object)
Syntax:
(gtk:text-mark-name object) => name
Arguments:
object -- a gtk:text-mark object
name -- a string with the name of the text mark
Details:
Accessor of the name slot of the gtk:text-mark class. The gtk:text-mark-name function returns the name of the text mark or nil for anonymous text marks.
See also:
2024-7-2
Function gtk:text-mark-new (name &optional gravity)
Arguments:
name -- a string with the name of the text mark or nil
gravity -- an optional boolean whether the text mark should have left gravity, the default is false
Returns:
The new gtk:text-mark object.
Details:
Creates a text mark. Add the text mark to a text buffer using the gtk:text-buffer-add-mark function. If the name argument is nil, the text mark is anonymous. Otherwise, the text mark can be retrieved by name using the gtk:text-buffer-mark function. If a text mark has left gravity, and text is inserted at the text current location of the text mark, the text mark will be moved to the left of the newly inserted text. If the text mark has right gravity, gravity is false, the text mark will end up on the right of newly inserted text. The standard left-to-right cursor is a text mark with right gravity, when you type, the cursor stays on the right side of the text you are typing.
See also:
2024-7-2
Function gtk:text-mark-visible (mark)
Syntax:
(gtk:text-mark-visible mark) => visibility
(setf (gtk:text-mark-visible mark) visibility)
Arguments:
mark -- a gtk:text-mark object
visibility -- a boolean whether the text mark is visible
Returns:
True if the text mark is visible.
Details:
The gtk:text-mark-visible function returns true if the text mark is visible, that is a cursor is displayed for it. The (setf gtk:text-mark-visible) function sets the visibility.

The insertion point is normally visible, that is, you can see it as a vertical bar. Also, the text widget uses a visible text mark to indicate where a drop will occur when dragging-and-dropping text. Most other text marks are not visible. Text marks are not visible by default.
See also:
2024-7-2
Function gtk:text-mark-deleted (mark)
Arguments:
mark -- a gtk:text-mark object
Returns:
True if the text mark is deleted.
Details:
Returns true if the text mark has been removed from its text buffer with the gtk:text-buffer-delete-mark function. See the gtk:text-buffer-add-mark function for a way to add the text mark to a text buffer again.
See also:
2024-7-2
Function gtk:text-mark-buffer (mark)
Arguments:
mark -- a gtk:text-mark object
Returns:
The gtk:text-buffer object of the text mark.
Details:
Gets the text buffer this text mark is located inside, or nil if the mark is deleted.
See also:
2024-7-2

GtkTextBuffer

GFlags gtk:text-buffer-notify-flags
Declaration:
(gobject:define-gflags "GtkTextBufferNotifyFlags" text-buffer-notify-flags
  (:export t
   :type-initializer "gtk_text_buffer_notify_flags_get_type")
  (:before-insert #.(ash 1 0))
  (:after-insert #.(ash 1 1))
  (:before-delete #.(ash 1 2))
  (:after-delete #.(ash 1 3)))  
Values:
:before-insert
Be notified before text is inserted into the underlying text buffer.
:after-insert
Be notified after text has been inserted into the underlying text buffer.
:before-delete
Be notified before text is deleted from the underlying text buffer.
:after-delete
Be notified after text has been deleted from the underlying text buffer.
Details:
Values for the gtk:text-buffer-commit-notify callback function to denote the point of the notification. Since 4.16
See also:
2024-10-26
Class gtk:text-buffer
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
can-redo
The can-redo property of type :boolean (Read)
The property denotes that the text buffer can reapply the last undone action.
Default value: false
can-undo
The can-undo property of type :boolean (Read)
The property denotes that the text buffer can undo the last applied action.
Default value: false
cursor-position
The cursor-position property of type :int (Read)
The position of the insert mark, as offset from the beginning of the text buffer. It is useful for getting notified when the cursor moves.
Allowed values: >= 0
Default value: 0
enable-undo
The enable-undow property of type :boolean (Read / Write)
The property denotes if support for undoing and redoing changes to the text buffer is allowed.
Default value: true
has-selection
The has-selection property of type :boolean (Read)
Whether the text buffer has some text currently selected.
Default value: false
tag-table
The tag-table property of type gtk:text-tag-table (Read / Write / Construct)
The tag table associated with the text buffer.
text
The text property of type :string (Read / Write)
The text content of the text buffer, without child widgets and images.
Default value: ""
Returned by:
Slot Access Functions:
Details:
Stores text and attributes for display in a gtk:text-view widget. You may wish to begin by reading the text widget conceptual overview which gives an overview of all the objects and data types related to the text widget and how they work together.

The gtk:text-buffer object can support undoing changes to the text buffer content, see the gtk:text-buffer-enable-undo function.
Signal Details:
The "apply-tag" signal
lambda (buffer tag start end)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
tag
The gtk:text-tag applied tag.
start
The gtk:text-iter start iterator of the range the tag is applied to.
end
The gtk:text-iter end iterator of the range the tag is applied to.
The signal is emitted to apply a tag to a range of text in a text buffer. Applying actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the start and end iterators, or has to revalidate them.
The "begin-user-action" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted at the beginning of a single user visible operation on a text buffer.
The "changed" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted when the content of a text buffer has changed.
The "delete-range" signal
lambda (buffer start end)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
start
The gtk:text-iter start iterator of the range to be deleted.
end
The gtk:text-iter end iterator of the range to be deleted.
The signal is emitted to delete a range from a text buffer. Note that if your handler runs before the default handler it must not invalidate the start and end iterators, or has to revalidate them. The default signal handler revalidates the start and end iterators to both point to the location where text was deleted. Handlers which run after the default handler do not have access to the deleted text.
The "end-user-action" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted at the end of a single user visible operation on the text buffer.
The "insert-child-anchor" signal
lambda (buffer location anchor)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
location
The gtk:text-iter position to insert anchor in buffer.
anchor
The gtk:text-child-anchor object to be inserted.
The signal is emitted to insert a gtk:text-child-anchor object in a text buffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the location iterator, or has to revalidate it. The default signal handler revalidates it to be placed after the inserted anchor.
The "insert-paintable" signal
lambda (buffer location paintable)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
location
The gtk:text-iter position to insert paintable in buffer.
paintable
The gdk:paintable object to be inserted.
The signal is emitted to insert a gdk:paintable object in a text buffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the location iterator, or has to revalidate it. The default signal handler revalidates it to be placed after the inserted paintable.
The "insert-text" signal
lambda (buffer location text len)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
location
The gtk:text-iter position to insert text in buffer.
text
The string with the UTF-8 text to be inserted.
len
The integer with the length of the inserted text in bytes.
The signal is emitted to insert text in a text buffer. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the location iterator, or has to revalidate it. The default signal handler revalidates it to point to the end of the inserted text.
The "mark-deleted" signal
lambda (buffer mark)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
mark
The gtk:text-mark object that was deleted.
The signal is emitted as notification after a gtk:text-mark object is deleted.
The "mark-set" signal
lambda (buffer location mark)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
location
The gtk:text-iter location of mark in buffer.
mark
The gtk:text-mark object that is set.
The signal is emitted as notification after a gtk:text-mark object is set.
The "modified-changed" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted when the modified bit of a text buffer flips.
The "paste-done" signal
lambda (buffer clipboard)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
clipboard
The gdk:clipboard object.
The signal is emitted after a paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text.
The "redo" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted when a request has been made to redo the previously undone operation.
The "remove-tag" signal
lambda (buffer tag start end)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
tag
The gtk:text-tag object to be removed.
start
The gtk:text-iter start iterator of the range the tag is removed from.
end
The gtk:text-iter end iterator of the range the tag is removed from.
The signal is emitted to remove all occurrences of tag from a range of text in a text buffer. Removal actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the start and end iterators, or has to revalidate them.
The "undo" signal
lambda (buffer)    :run-last      
buffer
The gtk:text-buffer object which received the signal.
The signal is emitted when a request has been made to undo the previous operation or set of operations that have been grouped together.
See also:
2024-7-3
Accessor gtk:text-buffer-can-redo (object)
Syntax:
(gtk:text-buffer-can-redo object) => setting
Arguments:
object -- a gtk:text-buffer object
setting -- true if there is an redoable action
Details:
Accessor of the can-redo slot of the gtk:text-buffer class. The gtk:text-buffer-can-redo function gets whether there is a redoable action in the history.
See also:
2024-7-3
Accessor gtk:text-buffer-can-undo (object)
Syntax:
(gtk:text-buffer-can-undo object) => setting
Arguments:
object -- a gtk:text-buffer object
setting -- true if there is an undoable action
Details:
Accessor of the can-undo slot of the gtk:text-buffer class. The gtk:text-buffer-can-undo function gets whether there is a undoable action in the history.
See also:
2024-7-3
Accessor gtk:text-buffer-cursor-position (object)
Syntax:
(gtk:text-buffer-cursor-position object) => position
Arguments:
object -- a gtk:text-buffer object
position -- an integer with the position of the insert mark
Details:
Accessor of the cursor-position slot of the gtk:text-buffer class. The position of the insert mark, as offset from the beginning of the text buffer. It is useful for getting notified when the cursor moves.
See also:
2024-7-3
Accessor gtk:text-buffer-enable-undo (object)
Syntax:
(gtk:text-buffer-cursor-position object) => setting
(setf (gtk:text-buffer-enable-undo object) setting)
Arguments:
object -- a gtk:text-buffer object
setting -- true to enable undo
Details:
Accessor of the enable-undo slot of the gtk:text-buffer class. The gtk:text-buffer-enable-undo function gets whether the text buffer is saving modifications to the text buffer to allow for undo and redo actions. The (setf gtk:text-buffer-enable-undo) sets whether or not to enable undoable actions in the text buffer. If enabled, the user will be able to undo the last number of actions up to the gtk:text-buffer-max-undo-levels value.

See the gtk:text-buffer-begin-irreversible-action and gtk:text-buffer-end-irreversible-action functions to create changes to the text buffer that cannot be undone.
See also:
2024-7-3
Accessor gtk:text-buffer-has-selection (object)
Syntax:
(gtk:text-buffer-has-selection object) => setting
Arguments:
object -- a gtk:text-buffer object
setting -- true if there is text selected
Details:
Accessor of the has-selection slot of the gtk:text-buffer class. Indicates whether the text buffer has some text currently selected.
See also:
2024-7-3
Accessor gtk:text-buffer-tag-table (object)
Syntax:
(gtk:text-buffer-tag-table object) => table
Arguments:
object -- a gtk:text-buffer object
table -- a gtk:text-tag-table object
Details:
Accessor of the tag-table slot of the gtk:text-buffer class. Gets the tag table associated with the text buffer.
See also:
2024-7-3
Accessor gtk:text-buffer-text (object)
Syntax:
(gtk:text-buffer-text object) => text
(setf (gtk:text-buffer-text object) text)
Arguments:
object -- a gtk:text-buffer object
text -- a string with the UTF-8 text
Details:
Accessor of the text slot of the gtk:text-buffer class. The gtk:text-buffer-text function retrieves the text of the text buffer, without child widgets and images. The (setf gtk:text-buffer-text) function deletes current contents of the text buffer, and inserts text instead. The text must be valid UTF-8.
Notes:
Use the gtk:text-buffer-get-text function to retrieve a range of text from the text buffer and the gtk:text-buffer-get-slice function to include widgets and images.
See also:
2024-7-3
Function gtk:text-buffer-new (&optional table)
Arguments:
table -- an optional gtk:text-tag-table object, or no argument to create a new one
Returns:
The new gtk:text-buffer object.
Details:
Creates a new text buffer.
See also:
2024-7-3
Function gtk:text-buffer-load-file (buffer path)
Arguments:
buffer -- a gtk:text-buffer object
path -- a pathname or namestring for the file to load
Details:
Loads a file into the given text buffer.
Notes:
This is a simple Lisp extension that does not exist in the C library.
See also:
2024-11-9
Function gtk:text-buffer-line-count (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The integer with the number of lines in the text buffer.
Details:
Obtains the number of lines in the text buffer. This value is cached, so the function is very fast.
See also:
2024-7-3
Function gtk:text-buffer-char-count (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The integer with the number of characters in the text buffer.
Details:
Gets the number of characters in the text buffer. Note that characters and bytes are not the same, you cannot, for example, expect the contents of the text buffer in string form to be this many bytes long. The character count is cached, so this function is very fast.
See also:
2024-7-3
Function gtk:text-buffer-insert (buffer pos text &key interactive editable)
Syntax:
(gtk:text-buffer-insert buffer pos text) => t
(gtk:text-buffer-insert buffer pos text :interactive t) => t
(gtk:text-buffer-insert buffer pos text :interactive t :editable t) => t
Arguments:
buffer -- a gtk:text-buffer object
pos -- a gtk:text-iter iterator or the :cursor value
text -- a string with the text in UTF-8 format
interactive -- a boolean whether the insertion is caused by user interaction, the default value is false
editable -- a boolean whether buffer is editable by default, the default value is false
Returns:
True if the text was actually inserted.
Details:
Inserts text in the text buffer. If the pos argument has the :cursor value, inserts the text using the current cursor position as the insertion point.

If the interactive keyword argument is true, the insertion will not occur if the iterator is at a non-editable location in the text buffer. Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive).

The editable keyword argument indicates the editability of text that does not have a tag affecting editability applied to it. Typically the result of the gtk:text-view-editable function is appropriate here.

Emits the "insert-text" signal. Insertion actually occurs in the default handler for the signal. The iterator is invalidated when insertion occurs, because the text buffer contents change, but the default signal handler revalidates it to point to the end of the inserted text.
Notes:
The gtk:text-buffer-insert function combines the gtk_text_buffer_insert(), gtk_text_buffer_insert_at_cursor(), gtk_text_buffer_insert_interactive(), and gtk_text_buffer_insert_interactive_at_cursor() functions into one function using the interactive, and editable keyword arguments. The corresponding Lisp functions except for the gtk:text-buffer-insert function are not exported in the Lisp implementation.
See also:
2024-7-3
Function gtk:text-buffer-insert-range (buffer iter start end &key interactive editable)
Syntax:
(gtk:text-buffer-insert-range buffer iter start end) => t
(gtk:text-buffer-insert-range buffer iter start end :interactive t) => t
(gtk:text-buffer-insert-range buffer iter start end :interactive t :editable t) => t
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter position in text buffer
start -- a gtk:text-iter start position
end -- a gtk:text-iter end position
interactive -- a boolean whether the deletion is caused by user interaction
editable -- a boolean whether buffer is editable by default
Returns:
True if the insertion was possible.
Details:
Copies text, tags, and paintables between the start and end iterators, the order of start and end does not matter, and inserts the copy at the iter iterator.

Used instead of simply getting/inserting text because it preserves images and tags. If start and end are in a different text buffer from buffer, the two buffers must share the same tag table.

The interactive keyword argument with the true value is the same, but does nothing if the insertion point is not editable. The editable keyword argument indicates whether the text is editable at the iterator if no tags enclosing the iterator affect editability. Typically the result of the gtk:text-view-editable function is appropriate here.

Implemented via emissions of the "insert-text" and "apply-tag" signals, so expect those.
Notes:
The Lisp implementation combines the two gtk_text_buffer_insert_range() and gtk_text_buffer_insert_range_interactive() functions. The second function is not exported in the Lisp implementation,
See also:
2024-7-3
Function gtk:text-buffer-insert-with-tags (buffer iter text &rest tags)
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter iterator in the text buffer
text -- a string with the UTF-8 text
tags -- a list with gtk:text-tag objects or strings with the tag names to apply to text
Details:
Inserts text into the text buffer at the position iter, applying the list of tags to the newly inserted text. Equivalent to calling the gtk:text-buffer-insert function, then the gtk:text-buffer-apply-tag function on the inserted text. The gtk:text-buffer-insert-with-tags function is just a convenience function.
Notes:
The Lisp implementation does not call the gtk_text_buffer_insert_with_tags() function, but uses the gtk:text-buffer-insert and gtk:text-buffer-apply-tag functions. The gtk_text_buffer_insert_with_tags_by_name() function is included in this function and not implemented in the Lisp library.
See also:
2024-7-3
Function gtk:text-buffer-insert-markup (buffer iter markup)
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter iterator with a position in the text buffer
markup -- a UTF-8 string containing Pango markup
Details:
Inserts the text in markup at the position of the iterator. The text in markup will be inserted in its entirety and must be valid UTF-8. Emits the "insert-text" signal, possibly multiple times. Insertion actually occurs in the default handler for the signal. The iterator will point to the end of the inserted text on return.
See also:
2024-7-3
Function gtk:text-buffer-insert-paintable (buffer iter paintable)
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter iterator with the location to insert the paintable
paintable -- a gdk:paintable object
Details:
Inserts an image into the text buffer at iter. The image will be counted as one character in character counts, and when obtaining the text buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the "slice" variants for obtaining portions of the text buffer as a string include this character for the paintable, but the ¸"text" variants do not. See the gtk:text-buffer-get-slice and gtk:text-buffer-get-text functions.
See also:
2024-7-3
Function gtk:text-buffer-delete (buffer start end &key interactive editable)
Syntax:
(gtk:text-buffer-delete buffer start end) => t
(gtk:text-buffer-delete buffer start end :interactive t) => t
(gtk:text-buffer-delete buffer start end :interactive t :editable t) => t
Arguments:
buffer -- a gtk:text-buffer object
start -- a gtk:text-iter start position in the text buffer
end -- a gtk:text-iter end position in the text buffer
interactive -- a boolean whether the deletion is caused by user interaction, the default value is nil
editable -- a boolean whether the text buffer is editable by default, the default value is nil
Returns:
True if some text was actually deleted.
Details:
Deletes text between the start and end iterators. The order of the start and end iterators is not actually relevant. The gtk:text-buffer-delete function will reorder them. This function actually emits the "delete-range" signal, and the default handler of that signal deletes the text. Because the text buffer is modified, all outstanding iterators become invalid after calling this function. However, the start and end interators will be re-initialized to point to the location where text was deleted.

If the interactive keyword argument is true deletes all editable text for each editable sub range of [start, end). The start and end iterators are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. If the editable keyword argument is true deletes in addition the not editable text. This case is equivalent to calling the gtk:text-buffer-delete function with the nil value for the interactive keyword argument.
Notes:
The gtk_text_buffer_delete_interactive() function is included in this function and not implemented in the Lisp libraray.
See also:
2024-7-26
Function gtk:text-buffer-backspace (buffer iter &key interactive editable)
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter position in buffer
interactive -- a boolean whether the deletion is caused by user interaction
editable -- a boolean whether buffer is editable by default
Returns:
True if the text buffer was modified.
Details:
Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by iter. In the normal case a single character will be deleted, but when combining accents are involved, more than one character can be deleted, and when precomposed character and accent combinations are involved, less than one character will be deleted.

Because the text buffer is modified, all outstanding iterators become invalid after calling this function. However, the iterator will be re-initialized to point to the location where text was deleted.
See also:
2024-7-3
Function gtk:text-buffer-get-text (buffer start end &optional include)
Arguments:
buffer -- a gtk:text-buffer object
start -- a gtk:text-iter start iterator of a range
end -- a gtk:text-iter end iterator of a range
include -- a boolean whether to include invisible text
Returns:
The allocated UTF-8 string.
Details:
Returns the text in the range [start, end). Excludes undisplayed text, text marked with tags that set the invisibility attribute, if the include argument is false. Does not include characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the text buffer. Contrast with the gtk:text-buffer-get-slice function.
See also:
2024-7-3
Function gtk:text-buffer-get-slice (buffer start end &optional include)
Arguments:
buffer -- a gtk:text-buffer object
start -- a gtk:text-iter start of a range
end -- a gtk:text-iter end of a range
include -- a boolean whether to include invisible text
Returns:
The allocated UTF-8 string.
Details:
Returns the text in the range [start, end). Excludes undisplayed text, text marked with tags that set the invisibility attribute, if the include argument is false.

The returned string includes a 0xFFFC character whenever the text buffer contains embedded images, so byte and character indexes into the returned string do correspond to byte and character indexes into the text buffer. Contrast with the gtk:text-buffer-get-text function. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-insert-child-anchor (buffer pos &optional anchor)
Arguments:
buffer -- a gtk:text-buffer object
pos -- a gtk:text-iter iterator with the position to insert the anchor
anchor -- an optional gtk:text-child-anchor object
Returns:
The gtk:text-child-anchor child widget anchor.
Details:
Inserts a child widget anchor into the text buffer at pos. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode "object replacement character" 0xFFFC. Note that the "slice" variants for obtaining portions of the text buffer as a string include this character for anchors, but the "text" variants do not, for example, see the gtk:text-buffer-get-slice and gtk:text-buffer-get-text functions. Consider the gtk:text-buffer-create-child-anchor function as a more convenient alternative to this function. The text buffer will add a reference to the anchor, so you can unref it after insertion.

If the anchor argument is nil creates an anchor with the gtk:text-child-anchor-new function and inserts it into buffer with the gtk:text-buffer-insert-child-anchor function. The new anchor is owned by the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-create-child-anchor (buffer iter)
Arguments:
buffer -- a gtk:text-buffer object
iter -- a gtk:text-iter location in the text buffer
Returns:
The created gtk:text-child-anchor anchor.
Details:
This is a convenience function which simply creates an anchor with the gtk:text-child-anchor-new function and inserts it into the text buffer with the gtk:text-buffer-insert-child-anchor function. The new anchor is owned by the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-create-mark (buffer name pos &optional gravity)
Arguments:
buffer -- a gtk:text-buffer object
name -- a string with the name for the mark, or nil
pos -- a gtk:text-iter iterator with the location to place the mark
gravity -- a boolean whether the mark has left gravity, the default is true
Returns:
The new gtk:text-mark object.
Details:
Creates a mark at position pos. If the mark argument is nil, the mark is anonymous. Otherwise, the mark can be retrieved by name using the gtk:text-buffer-mark function. If a mark has left gravity, and text is inserted at the current location of the mark, the mark will be moved to the left of the newly inserted text. If the mark has right gravity, the mark will end up on the right of newly inserted text. The standard left-to-right cursor is a mark with right gravity, when you type, the cursor stays on the right side of the text you are typing.

The caller of this function does not own a reference to the returned gtk:text-mark object, so you can ignore the return value if you like. Marks are owned by the text buffer and go away when the text buffer does.

Emits the "mark-set" signal as notification of the initial placement of the mark.
See also:
2024-7-3
Function gtk:text-buffer-move-mark (buffer mark pos)
Arguments:
buffer -- a gtk:text-buffer object
mark -- a gtk:text-mark object, or a string with the name of the mark
pos -- a gtk:text-iter iterator with the new position for mark in the text buffer
Details:
Moves the mark to the new location pos. Emits the "mark-set" signal as notification of the move.
See also:
2024-7-3
Function gtk:text-buffer-add-mark (buffer mark pos)
Arguments:
buffer -- a gtk:text-buffer object
mark -- a gtk:text-mark object with the mark to add
pos -- a gtk:text-iter iterator with the location to place the mark
Details:
Adds the mark at the given position. The mark must not be added to another text buffer, and if its name is not nil then there must not be another mark in the text buffer with the same name.

Emits the "mark-set" signal as notification of the initial placement of the mark.
See also:
2024-7-3
Function gtk:text-buffer-delete-mark (buffer mark)
Arguments:
buffer -- a gtk:text-buffer object
mark -- a gtk:text-mark object, or a string with the name of a mark in the text buffer
Details:
Deletes the mark, so that it is no longer located anywhere in the text buffer. Removes the reference the text buffer holds to the mark. Most operations on the mark become invalid, until it gets added to a text buffer again with the gtk:text-buffer-add-mark function. Use the gtk:text-mark-deleted function to find out if a mark has been removed from its text buffer. The "mark-deleted" signal will be emitted as notification after the mark is deleted.
Notes:
The gtk_text_buffer_delete_mark_by_name() function is included in this function and not exported in the Lisp library.
See also:
2024-7-3
Function gtk:text-buffer-mark (buffer name)
Arguments:
buffer -- a gtk:text-buffer object
name -- a string with a mark name
Returns:
The gtk:text-mark object, or nil.
Details:
Returns the mark named name in the text buffer, or nil if no such mark exists in the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-get-insert (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The gtk:text-mark object with the insertion point mark.
Details:
Returns the mark that represents the cursor (insertion point). Equivalent to calling the gtk:text-buffer-mark function to get the mark named "insert", but more efficient.
See also:
2024-7-3
Function gtk:text-buffer-selection-bound (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The gtk:text-mark object with the selection bound mark.
Details:
Returns the mark that represents the selection bound. Equivalent to calling the gtk:text-buffer-mark function to get the mark named "selection_bound", but very slightly more efficient, and involves less typing.

The currently selected text in the text buffer is the region between the "selection_bound" and "insert" marks. If the "selection_bound" and "insert" marks are in the same place, then there is no current selection. The gtk:text-buffer-selection-bounds function is another convenient function for handling the selection, if you just want to know whether there is a selection and what its bounds are.
See also:
2024-7-3
Function gtk:text-buffer-place-cursor (buffer pos)
Arguments:
buffer -- a gtk:text-buffer object
pos -- a gtk:text-iter iterator where to put the cursor
Details:
This function moves the "insert" and "selection_bound" marks simultaneously. If you move them to the same place in two steps with the gtk:text-buffer-move-mark function, you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized.
See also:
2024-7-3
Function gtk:text-buffer-select-range (buffer insertion selection)
Arguments:
buffer -- a gtk:text-buffer object
insertion -- a gtk:text-iter iterator where to put the "insert" mark
selection -- a gtk:text-iter iterator where to put the "selection_bound" mark
Details:
This function moves the "insert" and "selection_bound" marks simultaneously. If you move them in two steps with the gtk:text-buffer-move-mark function, you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized.
See also:
2024-7-3
Function gtk:text-buffer-apply-tag (buffer tag start end)
Arguments:
buffer -- a gtk:text-buffer object
tag -- a gtk:text-tag object, or a string with the tag name
start -- a gtk:text-iter iterator with the start bound of the range to be tagged
end -- a gtk:text-iter iterator with the end bound of the range to be tagged
Details:
Emits the "apply-tag" signal on the text buffer. The default handler for the signal applies tag to the given range. The start and end iterators do not have to be in order.
Notes:
The Lisp implementation combines the two gtk_text_buffer_apply_tag() and gtk_text_buffer_apply_tag_by_name() functions. The second funtion is not exported.
See also:
2024-7-3
Function gtk:text-buffer-remove-tag (buffer tag start end)
Arguments:
buffer -- a gtk:text-buffer object
tag -- a gtk:text-tag object, or a string with the tag name
start -- a gtk:text-iter iterator with the start bound of the range to be untagged
end -- a gtk:text-iter iterator with the end bound of the range to be untagged
Details:
Emits the "remove-tag" signal. The default handler for the signal removes all occurrences of tag from the given range. The start and end iterators do not have to be in order.
Notes:
The Lisp implementation combines the two gtk_text_buffer_remove_tag() and gtk_text_buffer_remove_tag_by_name() functions. The second funtion is not exported.
See also:
2024-7-3
Function gtk:text-buffer-remove-all-tags (buffer start end)
Arguments:
buffer -- a gtk:text-buffer object
start -- a gtk:text-iter iterator with the start bound of the range to be untagged
end -- a gtk:text-iter iterator with the end bound of the range to be untagged
Details:
Removes all tags in the range between the start and end iterators. Be careful with this function, it could remove tags added in code unrelated to the code you are currently writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections that add tags.
See also:
2024-7-3
Function gtk:text-buffer-create-tag (buffer name &rest args)
Arguments:
buffer -- a gtk:text-buffer object
name -- a string with the name of the new tag, or nil
args -- a list of property keywords and values
Returns:
The new gtk:text-tag object.
Details:
Creates a tag and adds it to the tag table for the text buffer. Equivalent to calling the gtk:text-tag-new function and then adding the tag to the tag table of the text buffer.

If the name argument is nil, the tag is anonymous. If the name argument is non-nil, a tag called name must not already exist in the tag table for this text buffer.

The args argument is a list of properties and values to set on the tag.
Examples:
Create and add a tag with name "font-italic" to the text buffer.
(defvar buffer (gtk:text-buffer-new)) => BUFFER
(gtk:text-buffer-create-tag buffer "font-italic"
                                   :font "fixed" :style :italic)
=> #<GTK:TEXT-TAG {1002193283}>    
See also:
2024-7-3
Function gtk:text-buffer-iter-at-line-offset (buffer line offset)
Arguments:
buffer -- a gtk:text-buffer object
line -- an integer with the line number counting from 0
offset -- an integer with the char offset from the start of the line
Returns:
The gtk:text-iter iterator.
Details:
Obtains an iterator pointing to offset within the given line. Note characters, not bytes, UTF-8 may encode one character as multiple bytes.

If the line argument is greater than the number of lines in the text buffer, the end iterator is returned. And if the offset argument is off the end of the line, the iterator at the end of the line is returned.
See also:
2024-7-3
Function gtk:text-buffer-iter-at-offset (buffer offset)
Arguments:
buffer -- a gtk:text-buffer object
offset -- an integer with the char offset from the start of the text buffer, counting from 0, or -1
Returns:
The gtk:text-iter iterator.
Details:
Initializes the returned iterator to a position offset chars from the start of the entire text buffer. If the offset argument is -1 or greater than the number of characters in the text buffer, the iterator is initialized to the end iterator, the iterator one past the last valid character in the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-iter-at-line (buffer line)
Arguments:
buffer -- a gtk:text-buffer object
line -- an integer with the line number counting from 0
Returns:
The gtk:text-iter iterator.
Details:
Initializes the returned iterator to the start of the given line.
See also:
2024-7-3
Function gtk:text-buffer-iter-at-line-index (buffer line index)
Arguments:
buffer -- a gtk:text-buffer object
line -- an integer with the line number counting from 0
index -- an integer with the byte index from the start of the line
Returns:
The gtk:text-iter iterator.
Details:
Obtains an iterator pointing to index within the given line. The index argument must be the start of a UTF-8 character. Note bytes, not characters, UTF-8 may encode one character as multiple bytes. If the line argument is greater than the number of lines in the text buffer, the end iterator is returned. And if the index argument is off the end of the line, the iterator at the end of the line is returned.
See also:
2024-7-3
Function gtk:text-buffer-iter-at-mark (buffer mark)
Arguments:
buffer -- a gtk:text-buffer object
mark -- a gtk:text-mark object, or a string with the mark name in the text buffer
Returns:
The gtk:text-iter iterator.
Details:
Returns the iterator with the current position of mark.
See also:
2024-7-3
Function gtk:text-buffer-iter-at-child-anchor (buffer anchor)
Arguments:
buffer -- a gtk:text-buffer object
anchor -- a gtk:text-child-anchor anchor that appears in text buffer
Returns:
The gtk:text-iter iterator.
Details:
Obtains the location of anchor within the text buffer.
See also:
2024-7-3
Function gtk:text-buffer-start-iter (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The gtk:text-iter iterator.
Details:
Returns an iterator with the first position in the text buffer. This is the same as using the gtk:text-buffer-iter-at-offset function to get the itererator at character offset 0.
See also:
2024-7-3
Function gtk:text-buffer-end-iter (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The gtk:text-iter iterator.
Details:
Returns an iterator with the "end iterator", one past the last valid character in the text buffer. If dereferenced with the gtk:text-iter-char function, the end iterator has a character value of 0. The entire text buffer lies in the range from the first position in the text buffer to the end iterator. Call the gtk:text-buffer-start-iter function to get character position 0.
See also:
2024-7-3
Function gtk:text-buffer-bounds (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
start -- a gtk:text-iter iterator with the first position in the text buffer
end -- a gtk:text-iter iterator with the end position in the text buffer
Details:
Retrieves the first and last iterators in the text buffer. The entire text buffer lies within the range [start, end).
Examples:
Get the start and end itererator for a text buffer and clear the text buffer.
(defun clear-buffer (buffer)
  (multiple-value-bind (start end)
      (gtk:text-buffer-bounds buffer)
    (gtk:text-buffer-delete buffer start end)))    
See also:
2024-7-3
Function gtk:text-buffer-modified (buffer)
Syntax:
(gtk:text-buffer-modified buffer) => setting
(setf (gtk:text-buffer-modified buffer) setting)
Arguments:
buffer -- a gtk:text-buffer object
setting -- a boolean with the modification flag setting
Details:
Returns true if the text buffer has been modified. The gtk:text-buffer-modified function indicates whether the text buffer has been modified since the last call to the (setf gtk:text-buffer-modified) function.

Used to keep track of whether the text buffer has been modified since the last time it was saved. Whenever the text buffer is saved to disk, call the (setf gtk:text-buffer-modified) function with the false value. When the text buffer is modified, it will automatically toggle on the modified bit again. When the modified bit flips, the text buffer emits a "modified-changed" signal.
See also:
2024-7-3
Function gtk:text-buffer-delete-selection (buffer &key interactive editable)
Arguments:
buffer -- a gtk:text-buffer object
interactive -- a boolean whether the deletion is caused by user interaction
editable -- a boolean whether the text buffer is editable by default
Returns:
The boolean whether there was a non-empty selection to delete.
Details:
Deletes the range between the "insert" and "selection_bound" marks, that is, the currently selected text. If the interactive argument is true, the editability of the selection will be considered, users cannot delete uneditable text.
See also:
#2024-7-3
Function gtk:text-buffer-paste-clipboard (buffer clipboard &key override editable)
Arguments:
buffer -- a gtk:text-buffer object
clipboard -- a gdk:clipboard object to paste from
override -- a gtk:text-iter location to insert pasted text, or nil to insert at the cursor
editable -- a boolean whether the text buffer is editable by default
Details:
Pastes the contents of a clipboard. If the override argument is nil, the pasted text will be inserted at the cursor position, or the buffer selection will be replaced if the selection is non-empty.
Notes:
Pasting is asynchronous, that is, we will ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted.
See also:
#2024-7-3
Function gtk:text-buffer-copy-clipboard (buffer clipboard)
Arguments:
buffer -- a gtk:text-buffer object
clipboard -- a gdk:clipboard object to copy to
Details:
Copies the currently selected text to the clipboard.
See also:
#2024-7-3
Function gtk:text-buffer-cut-clipboard (buffer clipboard editable)
Arguments:
buffer -- a gtk:text-buffer object
clipboard -- a gdk:clipboard object to cut to
editable -- a boolean whether the text buffer is editable by default
Details:
Copies the currently selected text to a clipboard, then deletes the text if it is editable.
See also:
#2024-7-3
Function gtk:text-buffer-selection-bounds (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
start -- a gtk:text-iter iterator with the selection start
end -- a gtk:text-iter iterator with the selection end
nil -- if no text is selected
Details:
Returns the start and end iterators if some text is selected. If the selection has length 0, then the start and end iterators are filled in with the same value. The start and end iterators will be in ascending order.
See also:
2024-7-3
Function gtk:text-buffer-selection-content (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
Details:
Get a content provider for this text buffer. It can be used to make the content of the text buffer available in a gdk:clipboard object, see the gdk:clipboard-content function.
See also:
#2024-7-3
Function gtk:text-buffer-begin-user-action (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Called to indicate that the text buffer operations between here and a call to the gtk:text-buffer-end-user-action function are part of a single user visible operation. The operations between the gtk:text-buffer-begin-user-action and gtk:text-buffer-end-user-action functions can then be grouped when creating an undo stack. The text buffer maintains a count of calls to the gtk:text-buffer-begin-user-action function that have not been closed with a call to the gtk:text-buffer-end-user-action function, and emits the "begin-user-action" and "end-user-action" signals only for the outermost pair of calls. This allows you to build user actions from other user actions.

The "interactive" text buffer mutation functions automatically call begin/end user action around the text buffer operations they perform, so there is no need to add extra calls if the user action consists solely of a single call to one of those functions.
See also:
#2024-7-3
Function gtk:text-buffer-end-user-action (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Should be paired with a call to the gtk:text-buffer-begin-user-action function. See that function for a full explanation.
See also:
#2024-7-3
Function gtk:text-buffer-add-selection-clipboard (buffer clipboard)
Arguments:
buffer -- a gtk:text-buffer object
clipboard -- a gdk:clipboard object
Details:
Adds a clipboard to the list of clipboards in which the selection contents of the text buffer are available. In most cases, the clipboard will be of type "PRIMARY" for a view of the text buffer.
See also:
#2024-7-3
Function gtk:text-buffer-remove-selection-clipboard (buffer clipboard)
Arguments:
buffer -- a gtk:text-buffer object
clipboard -- a gdk:clipboard object added to the text buffer
Details:
Removes a clipboard added with the gtk:text-buffer-add-selection-clipboard function.
See also:
#2024-7-3
Function gtk:text-buffer-max-undo-levels (buffer)
Syntax:
(gtk:text-buffer-max-undo-levels buffer) => levels
(setf (gtk:text-buffer-max-undo-levels buffer) levels)
Arguments:
buffer -- a gtk:text-buffer object
levels -- an unsigned integer with the number of undo levels
Details:
The gtk:text-buffer-max-undo-levels function gets the maximum number of undo levels to perform. The (setf gtk:text-buffer-max-undo-levels) function sets the maximum number. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer.
See also:
#2024-7-3
Function gtk:text-buffer-undo (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Undoes the last undoable action on the text buffer, if there is one.
See also:
#2024-7-3
Function gtk:text-buffer-redo (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Redoes the next redoable action on the text buffer, if there is one.
See also:
#2024-7-3
Function gtk:text-buffer-begin-irreversible-action (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Denotes the beginning of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be paired with a call to the gtk:text-buffer-end-irreversible-action function after the irreversible action has completed.

You may nest calls to the gtk:text-buffer-begin-irreversible-action and gtk:text-buffer-end-irreversible-action function pairs.
See also:
2024-7-3
Function gtk:text-buffer-end-irreversible-action (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Details:
Denotes the end of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be called after completing modifications to the text buffer after the gtk:text-buffer-begin-irreversible-action function was called.

You may nest calls to the gtk:text-buffer-begin-irreversible-action and gtk:text-buffer-end-irreversible-action function pairs.
See also:
2024-7-3
Callback gtk:text-buffer-commit-notify
Syntax:
lambda (buffer flags pos len)
Arguments:
buffer -- a gtk:text-buffer object being notified
flags -- a gtk:text-buffer-notify-flags value for the type of commit notification
pos -- an unsigned integer with the position of the text operation
len -- an unsigned integer with the length of the text operation in characters
Details:
A notification callback used by the gtk:text-buffer-add-commit-notify function. You may not modify the gtk:text-buffer object from a gtk:text-buffer-commit-notify callback function and that is enforced by the gtk:text-buffer API.

The gtk:text-buffer-commit-notify callback function may be used to be notified about changes to the underlying text buffer right before or after the changes are committed to the underlying B-Tree. This is useful if you want to observe changes to the text buffer without other signal handlers potentially modifying state on the way to the default signal handler.

When the flags argument is :before-insert, the pos argument is set to the offset in characters from the start of the text buffer where the insertion will occur. The len argument is set to the number of characters to be inserted. You may not yet retrieve the text until it has been inserted. You may access the text from :after-insert using the gtk:text-buffer-get-slice function.

When the flags argument is :after-insert, the pos argument is set to offset in characters where the insertion occurred and len is set to the number of characters inserted.

When the flags argument is :before-delete, the pos argument is set to offset in characters where the deletion will occur and len is set to the number of characters that will be removed. You may still retrieve the text from this handler using pos and len.

When the flags argument is :after-delete, the len argument is set to zero to denote that the delete-range has already been committed to the underlying B-Tree. You may no longer retrieve the text that has been deleted from the text buffer.

Since 4.16
See also:
#2024-10-26
Function gtk:text-buffer-add-commit-notify (buffer flags notify)
Arguments:
buffer -- a gtk:text-buffer object
flags -- a gtk:text-buffer-notify-flags value for which notifications should be dispatched to notify
notify -- a gtk:text-buffer-commit-notify callback function to call for commit notifications
Returns:
The unsigned integer with a handler ID which may be used to remove the commit notify callback using the gtk:text-buffer-remove-commit-notify function.
Details:
Adds a gtk:text-buffer-commit-notify callback function to be called when a change is to be made to the text buffer. Functions are explicitly forbidden from making changes to the text buffer from this callback. It is intended for tracking changes to the text buffer only.

It may be advantageous to use the gtk:text-buffer-commit-notify callback function over connecting to the GtkTextBuffer::insert-text signal or the GtkTextBuffer::delete-range signal to avoid ordering issues with other signal handlers which may further modify the text buffer.

Since 4.16
See also:
#2024-10-26
Function gtk:text-buffer-remove-commit-notify (buffer notifyid)
Arguments:
buffer -- a gtk:text-buffer object
notifyid -- an unsigned integer with the notify handler identifier
Details:
Removes the gtk:text-buffer-commit-notify handler previously registered with the gtk:text-buffer-add-commit-notify function.

Since 4.16
See also:
#2024-10-26

GtkChildAnchor

Class gtk:text-child-anchor
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:text-child-anchor object is a spot in the text buffer where child widgets can be "anchored", inserted inline, as if they were characters. The anchor can have multiple widgets anchored, to allow for multiple views.
See also:
2024-7-4
Function gtk:text-child-anchor-new ()
Returns:
The new gtk:text-child-anchor object.
Details:
Creates a new gtk:text-child-anchor object. Usually you would then insert it into a text buffer with the gtk:text-buffer-insert-child-anchor function. To create and insert in one step, use the gtk:text-buffer-create-child-anchor function.
See also:
2024-10-26
Function gtk:text-child-anchor-new-with-replacement (char)
Arguments:
character -- a string with a replacement character
Returns:
The new gtk:text-child-anchor object.
Details:
Creates a new gtk:text-child-anchor object with the given replacement character. Usually you would then insert it into a gtk:text-buffer object with the gtk:text-buffer-insert-child-anchor function.

Since 4.6
See also:
2024-10-26
Function gtk:text-child-anchor-widgets (anchor)
Arguments:
anchor -- a gtk:text-child-anchor object
Returns:
List of gtk:widget objects anchored at anchor.
Details:
Gets a list of all widgets anchored at the anchor.
See also:
2024-7-4
Function gtk:text-child-anchor-deleted (anchor)
Arguments:
anchor -- a gtk:text-child-anchor object
Returns:
True if the anchor has been deleted from its text buffer.
Details:
Determines whether a anchor has been deleted from the text buffer. Keep in mind that the anchor will be unreferenced when removed from the text buffer, so you need to hold your own reference if you plan to use this function - otherwise all deleted anchors will also be finalized.
See also:
2024-7-4

GtkTextView

GEnum gtk:text-window-type
Declaration:
(gobject:define-genum "GtkTextWindowType" text-window-type
  (:export t
   :type-initializer "gtk_text_window_type_get_type")
  (:widget 1)
  (:text 2)
  (:left 3)
  (:right 4)
  (:top 5)
  (:bottom 6))  
Values:
:widget
Window that floats over scrolling areas.
:text
Scrollable text window.
:left
Left side border window.
:right
Right side border window.
:top
Top border window.
:bottom
Bottom border window.
Details:
Used to reference the parts of the gtk:text-view widget.
See also:
2024-7-4
GEnum gtk:text-extend-selection
Declaration:
(gobject:define-genum "GtkTextExtendSelection" text-extend-selection
  (:export t
   :type-initializer "gtk_text_extend_selection_get_type")
  (:word 0)
  (:line 1))  
Values:
:word
Selects the current word. It is triggered by a double click for example.
:line
Selects the current line. It is triggered by a triple click for example.
Details:
Granularity types that extend the text selection. Use the "extend-selection" signal to customize the selection.
See also:
2024-7-4
Class gtk:text-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
accepts-tab
The accepts-tab property of type :boolean (Read / Write)
Whether the Tab key will result in a tab character being entered.
Default value: true
bottom-margin
The bottom-margin property of type :int (Read / Write)
The bottom margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Do not confuse this property with the margin-bottom property.
Allowed values: >= 0
Default value: 0
buffer
The buffer property of type gtk:text-buffer (Read / Write)
The text buffer which is displayed.
cursor-visible
The cursor-visible property of type :boolean (Read / Write)
Whether the insertion cursor is shown.
Default value: true
editable
The editable property of type :boolean (Read / Write)
Whether the text can be modified by the user.
Default value: true
extra-menu
The extra-menu property of type g:menu-model (Read / Write)
The menu model to append to the context menu.
im-module
The im-module property of type :string (Read / Write)
The IM (input method) module that should be used for the text view. See the gtk:im-context documentation. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module setting.
Default value: nil
indent
The indent property of type :int (Read / Write)
The amount to indent the paragraph, in pixels.
Default value: 0
input-hints
The input-hints property of type gtk:input-hints (Read / Write)
The additional hints, beyond the "input-purpose" signal, that allow input methods to fine-tune their behaviour.
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
The purpose of the text view. This property can be used by on-screen keyboards and other input methods to adjust their behaviour.
Default value: :free-form
justification
The justification property of type gtk:justification (Read / Write)
The left, right, or center justification.
Default value: :left
left-margin
The left-margin property of type :int (Read / Write)
The width of the left margin in pixels.
Allowed values: >= 0
Default value: 0
monospace
The monospace property of type :boolean (Read / Write)
Whether to use a monospace font.
Default value: false
overwrite
The overwrite property of type :boolean (Read / Write)
Whether entered text overwrites existing contents.
Default value: false
pixels-above-lines
The pixels-above-lines property of type :int (Read / Write)
The pixels of blank space above paragraphs.
Allowed values: >= 0
Default value: 0
pixels-below-lines
The pixels-below-lines property of type :int (Read / Write)
The pixels of blank space below paragraphs.
Allowed values: >= 0
Default value: 0
pixels-inside-wrap
The pixels-inside-wrap property of type :int (Read / Write)
The pixels of blank space between wrapped lines in a paragraph.
Allowed values: >= 0
Default value: 0
right-margin
The right-margin property of type :int (Read / Write)
The width of the right margin in pixels.
Allowed values: >= 0
Default value: 0
tabs
The tabs property of type pango:tab-array (Read / Write)
The custom tabs for this text.
top-margin
The top-margin property of type :int (Read / Write)
The top margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Do not confuse this property with the margin-top property.
Allowed values: >= 0
Default value: 0
wrap-mode
The wrap-mode property of type gtk:wrap-mode (Read / Write)
Whether to wrap lines never, at word boundaries, or at character boundaries.
Default value: :none
Returned by:
Slot Access Functions:
Details:
GTK has a powerful framework for multiline text editing.

Figure: GtkTextView

The primary objects involved in the process are the gtk:text-buffer object, which represents the text being edited, and the gtk:text-view widget, a widget which can display a gtk:text-buffer object. Each text buffer can be displayed by any number of views.
CSS nodes:
textview.view
├── border.top
├── border.left
├── text
│   ╰── [selection]
├── border.right
├── border.bottom
╰── [window.popup]    
The gtk:text-view implementation has a main CSS node with name textview and .view style class, and subnodes for each of the border windows, and the main text area, with names border and text, respectively. The border nodes each get one of the .left, .right, .top or .bottom style classes.

A node representing the selection will appear below the text node. If a context menu is opened, the window node will appear as a subnode of the main node.
Accessibility:
The gtk:text-view implmementation uses the :text-box role of the gtk:accessible-role enumeration.
Signal Details:
The "backspace" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted when the user asks for it. The default bindings for this signal are the Backspace and Shift-Backspace keys.
The "copy-clipboard" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted to copy the selection to the clipboard. The default bindings for this signal are the Ctrl-c and Ctrl-Insert keys.
The "cut-clipboard" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted to cut the selection to the clipboard. The default bindings for this signal are the Ctrl-x and Shift-Delete keys.
The "delete-from-cursor" signal
lambda (view granularity count)    :action      
view
The gtk:text-view widget which received the signal.
granularity
The granularity of the deletion, as a value of the gtk:delete-type enumeration.
count
The integer with the number of type units to delete.
The signal is a keybinding signal which gets emitted when the user initiates a text deletion. If the granularity is :chars, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are the Delete key for deleting a character, the Ctrl-Delete key for deleting a word and the Ctrl-Backspace key for deleting a word backwords.
The "extend-selection" signal
lambda (view granularity location start end)    :run-last      
view
The gtk:text-view widget which received the signal.
granularity
The granularity as a value of the gtk:text-extend-selection enumeration.
location
The gtk:text-iter iterator where to extend the selection.
start
The gtk:text-iter iterator where the selection should start.
end
The gtk:text-iter iterator where the selection should end.
Returns
True to stop other handlers from being invoked for the event, false to propagate the event further.
The signal is emitted when the selection needs to be extended at the location iterator.
The "insert-at-cursor" signal
lambda (view text)    :action      
view
The gtk:text-view widget which received the signal.
text
The string with the text to insert.
The signal is a keybinding signal which gets emitted when the user initiates the insertion of text at the cursor. The signal has no default bindings.
The "insert-emoji" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
This signal is a keybinding signal which gets emitted to present the Emoji chooser for the text view. The default bindings for this signal are Ctrl-. and Ctrl-;.
The "move-cursor" signal
lambda (view step count extend)    :action      
view
The gtk:text-view widget which received the signal.
step
The granularity of the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
extend
True if the move should extend the selection.
The signal is a keybinding signal which gets emitted when the user initiates a cursor movement. If the cursor is not visible in the text view, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifer does not. There are too many key combinations to list them all here. Arrow keys move by individual characters/lines. The Ctrl-arrow key combinations move by words/paragraphs. The Home/End keys move to the ends of the text buffer. The PageUp/PageDown keys move vertically by pages. The Ctrl-PageUp/PageDown keys move horizontally by pages.
The "move-viewport" signal
lambda (view step count)    :action      
view
The gtk:text-view widget which received the signal.
step
The granularity of the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
The signal is a keybinding signal which can be bound to key combinations to allow the user to move the viewport, that is, to change what part of the text view is visible in a scrolled window. There are no default bindings for this signal.
The "paste-clipboard" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted to paste the contents of the clipboard into the text view. The default bindings for this signal are the Ctrl-v and Shift-Insert keys.
The "preedit-changed" signal
lambda (view preedit)    :action      
view
The gtk:text-view object which received the signal.
preedit
The string with the current preedit text.
If an input method is used, the typed text will not immediately be committed to the text buffer. So if you are interested in the text, connect to this signal. The signal is only emitted if the text at the given position is actually editable.
The "select-all" signal
lambda (view select)    :action      
view
The gtk:text-view widget which received the signal.
select
True to select, false to unselect.
The signal is a keybinding signal which gets emitted to select or unselect the complete contents of the text view. The default bindings for the signal are the Ctrl-a and Ctrl-/ keys for selecting and the Shift-Ctrl-a and Ctrl- keys for unselecting.
The "set-anchor" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted when the user initiates setting the "anchor" mark. The "anchor" mark gets placed at the same position as the "insert" mark. The signal has no default bindings.
The "toggle-cursor-visible" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
This signal is a keybinding signal which gets emitted to toggle the visibility of the cursor. The default binding for this signal is F7.
The "toggle-overwrite" signal
lambda (view)    :action      
view
The gtk:text-view widget which received the signal.
The signal is a keybinding signal which gets emitted to toggle the overwrite mode of the text view. The default bindings for this signal is the Insert key.
See also:
2024-7-4
Accessor gtk:text-view-accepts-tab (object)
Syntax:
(gtk:text-view-accepts-tab object) => accepts
(setf (gtk:text-view-accepts-tab object) accepts)
Arguments:
object -- a gtk:text-view widget
accepts -- true if pressing the Tab key should insert a tab character, false, if pressing the Tab key should move the keyboard focus
Details:
Accessor of the accepts-tab slot of the gtk:text-view class. The gtk:text-view-accepts-tab function returns the behavior of the text view when the Tab key is pressed. The (setf gtk:text-view-accepts-tab) function sets the behavior.

If the accepts argument is true, a tab character is inserted. If the accepts argument is false the keyboard focus is moved to the next widget in the focus chain.
See also:
2024-7-4
Accessor gtk:text-view-bottom-margin (object)
Syntax:
(gtk:text-view-bottom-margin object) => margin
(setf (gtk:text-view-bottom-margin object) margin)
Arguments:
object -- a gtk:text-view widget
margin -- an integer with the bottom margin in pixels
Details:
Accessor of the bottom-margin slot of the gtk:text-view class. The gtk:text-view-bottom-margin function gets the bottom margin for text in the text view. The (setf gtk:text-view-bottom-margin) function sets the bottom margin.

Note that this function is confusingly named. In CSS terms, the value set here is padding.
See also:
2024-7-4
Accessor gtk:text-view-buffer (object)
Syntax:
(gtk:text-view-buffer object) => buffer
(setf (gtk:text-view-buffer object) buffer)
Arguments:
object -- a gtk:text-view widget
buffer -- a gtk:text-buffer object
Details:
Accessor of the buffer slot of the gtk:text-view class. The gtk:text-view-buffer function returns the text buffer being displayed by the text view. The (setf gtk:text-view-buffer) function sets the text buffer.
See also:
2024-7-4
Accessor gtk:text-view-cursor-visible (object)
Syntax:
(gtk:text-view-cursor-visible object) => setting
(setf (gtk:text-view-cursor-visible object) setting)
Arguments:
object -- a gtk:text-view widget
setting -- a boolean whether to show the insertion cursor
Details:
Accessor of the cursor-visible slot of the gtk:text-view class. The gtk:text-view-cursor-visible function returns whether the insertion mark is visible. The (setf gtk:text-view-cursor-visible) function toggles whether the insertion point is displayed.

A text buffer with no editable text probably should not have a visible cursor, so you may want to turn the cursor off.
See also:
2024-7-4
Accessor gtk:text-view-editable (object)
Syntax:
(gtk:text-view-editable object) => setting
(setf (gtk:text-view-editable object) setting)
Arguments:
object -- a gtk:text-view widget
setting -- a boolean whether the text view is editable
Details:
Accessor of the editable slot of the gtk:text-view class. The gtk:text-view-editable function returns the default editability of the text view. The (setf gtk:text-view-editable) function sets the default editability.

You can override this default setting with tags in the text buffer, using the editable attribute of tags.
See also:
2024-7-4
Accessor gtk:text-view-extra-menu (object)
Syntax:
(gtk:text-view-extra-menu object) => menu
(setf (gtk:text-view-extra-menu object) menu)
Arguments:
object -- a gtk:text-view widget
menu -- a g:menu-model object
Details:
Accessor of the extra-menu slot of the gtk:text-view class. The gtk:text-view-extra-menu function gets the menu model. The (setf gtk:text-view-extra-menu) function sets a menu model to add when constructing the context menu for the text view. You can pass nil to remove a previously set extra menu.
See also:
2024-7-4
Accessor gtk:text-view-im-module (object)
Syntax:
(gtk:text-view-im-module object) => module
(setf (gtk:text-view-im-module object) module)
Arguments:
object -- a gtk:text-view widget
module -- a string with the IM module to use for the text view
Details:
Accessor of the im-module slot of the gtk:text-view class. Which IM (input method) module should be used for the text view. See the gtk:im-context class. Setting this to a non-nil value overrides the system-wide IM module setting. See the gtk-im-module setting.
See also:
2024-7-4
Accessor gtk:text-view-indent (object)
Syntax:
(gtk:text-view-indent object) => indent
(setf (gtk:text-view-indent object) indent)
Arguments:
object -- a gtk:text-view widget
indent -- an integer with the indentation in pixels
Details:
Accessor of the indent slot of the gtk:text-view class. The gtk:text-view-indent function gets the default indentation of paragraphs in the text view. The (setf gtk:text-view-indent) function sets the default indentation.

Tags in the text buffer of the text view may override the default. The indentation may be negative.
See also:
2024-7-4
Accessor gtk:text-view-input-hints (object)
Syntax:
(gtk:text-view-input-hints object) => hints
(setf (gtk:text-view-input-hints object) hints)
Arguments:
object -- a gtk:text-view widget
hints -- a gtk:input-hints value with the hints
Details:
Accessor of the input-hints slot of the gtk:text-view class. The gtk:text-view-input-hints function gets the value of the input-hints property, which allows input methods to fine-tune their behaviour. The (setf gtk:text-view-input-hints) function sets the property.
See also:
2024-7-4
Accessor gtk:text-view-input-purpose (object)
Syntax:
(gtk:text-view-input-purpose object) => purpose
(setf (gtk:text-view-input-purpose object) purpose)
Arguments:
object -- a gtk:text-view widget
purpose -- a gtk:input-purpose value with the purpose
Details:
Accessor of the input-purpose slot of the gtk:text-view class. The gtk:text-view-input-purpose function gets the value of the input-purpose property, which can be used by on-screen keyboards and other input methods to adjust their behaviour. The (setf gtk:text-view-input-purpose) function sets the property.
See also:
2024-7-4
Accessor gtk:text-view-justification (object)
Syntax:
(gtk:text-view-justification object) => justification
(setf (gtk:text-view-justification object) justification)
Arguments:
object -- a gtk:text-view widget
justification -- a value of the gtk:justification enumeration
Details:
Accessor of the justification slot of the gtk:text-view class. The gtk:text-view-justification function gets the default justification of paragraphs in the text view. The (setf gtk:text-view-justification) function sets the default justification. Tags in the text buffer may override the default.
See also:
2024-7-4
Accessor gtk:text-view-left-margin (object)
Syntax:
(gtk:text-view-left-margin object) => margin
(setf (gtk:text-view-left-margin object) margin)
Arguments:
object -- a gtk:text-view widget
margin -- an integer with the left margin in pixels
Details:
Accessor of the left-margin slot of the gtk:text-view class. The gtk:text-view-left-margin function gets the default left margin size of paragraphs in the text view. The (setf gtk:text-view-left-margin) function sets the default left margin.

Tags in the text buffer may override the default.
See also:
2024-7-4
Accessor gtk:text-view-monospace (object)
Syntax:
(gtk:text-view-monospace object) => monospace
(setf (gtk:text-view-monospace object) monospace)
Arguments:
object -- a gtk:text-view widget
monospace -- true to request monospace styling
Details:
Accessor of the monospace slot of the gtk:text-view class. The gtk:text-view-monospace function gets the value of the monospace property, which indicates that the text view should use monospace fonts. The (setf gtk:text-view-monospace) function sets the property.
See also:
2024-7-4
Accessor gtk:text-view-overwrite (object)
Syntax:
(gtk:text-view-overwrite object) => overwrite
(setf (gtk:text-view-overwrite object) overwrite)
Arguments:
object -- a gtk:text-view widget
overwrite -- true to turn on overwrite mode, false to turn it off
Details:
Accessor of the overwrite slot of the gtk:text-view class. The gtk:text-view-overwrite function returns whether the text view is in overwrite mode or not. The (setf gtk:text-view-overwrite) function changes the overwrite mode.
See also:
2024-7-4
Accessor gtk:text-view-pixels-above-lines (object)
Syntax:
(gtk:text-view-pixels-above-lines object) => pixels
(setf (gtk:text-view-pixels-above-lines object) pixels)
Arguments:
object -- a gtk:text-view widget
pixels -- an integer with the pixels above paragraphs
Details:
Accessor of the pixels-above-lines slot of the gtk:text-view class. The gtk:text-view-pixels-above-lines function gets the default number of pixels to put above paragraphs in the text view. The (setf gtk:text-view-pixels-above-lines) function sets the default number of blank pixels.

Tags in the text buffer for the text view may override the defaults.
See also:
2024-7-4
Accessor gtk:text-view-pixels-below-lines (object)
Syntax:
(gtk:text-view-pixels-below-lines object) => pixels
(setf (gtk:text-view-pixels-below-lines object) pixels)
Arguments:
object -- a gtk:text-view widget
pixels -- an integer with the pixels below paragraphs
Details:
Accessor of the pixels-below-lines slot of the gtk:text-view class. The gtk:text-view-pixels-below-lines function gets the default number of pixels to put below paragraphs in the text view. The (setf gtk:text-view-pixels-below-lines) function sets the default number of pixels of blank space to put below paragraphs.

May be overridden by tags applied to the text buffer of the text view.
See also:
2024-7-4
Accessor gtk:text-view-pixels-inside-wrap (object)
Syntax:
(gtk:text-view-pixels-inside-wrap object) => pixels
(setf (gtk:text-view-pixels-inside-wrap object) pixels)
Arguments:
object -- a gtk:text-view widget
pixels -- an integer with the default number of pixels between wrapped lines
Details:
Accessor of the pixels-inside-wrap slot of the gtk:text-view class. The gtk:text-view-pixels-inside-wrap function gets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. The (setf gtk:text-view-pixels-inside-wrap) function sets the default number of pixels.

May be overridden by tags in the text buffer of the text view.
See also:
2024-7-4
Accessor gtk:text-view-right-margin (object)
Syntax:
(gtk:text-view-right-margin object) => margin
(setf (gtk:text-view-right-margin object) margin)
Arguments:
object -- a gtk:text-view widget
margin -- an integer with the right margin in pixels
Details:
Accessor of the right-margin slot of the gtk:text-view class. The gtk:text-view-right-margin function gets the default right margin for text in the text view. The (setf gtk:text-view-right-margin) function sets the default right margin.

Tags in the text buffer may override the default.
See also:
2024-7-4
Accessor gtk:text-view-tabs (object)
Syntax:
(gtk:text-view-tabs object) => tabs
(setf (gtk:text-view-tabs object) tabs)
Arguments:
object -- a gtk:text-view widget
tabs -- a pango:tab-array instance with the tabs
Details:
Accessor of the tabs slot of the gtk:text-view class. The gtk:text-view-tabs function gets a copy of the default Pango tab array, or nil if "standard" tabs are used. The (setf gtk:text-view-tabs) function sets the default tab stops for paragraphs.

Tags in the text buffer may override the defaults.
See also:
2024-7-4
Accessor gtk:text-view-top-margin (object)
Syntax:
(gtk:text-view-top-margin object) => margin
(setf (gtk:text-view-top-margin object) margin)
Arguments:
object -- a gtk:text-view widget
margin -- an integer with the top margin in pixels
Details:
Accessor of the top-margin slot of the gtk:text-view class. The gtk:text-view-top-margin function gets the top margin for text in the text view. The (setf gtk:text-view-top-margin) function sets the top margin.

Note that this function is confusingly named. In CSS terms, the value set here is padding.
See also:
2024-7-4
Accessor gtk:text-view-wrap-mode (object)
Syntax:
(gtk:text-view-wrap-mode object) => mode
(setf (gtk:text-view-wrap-mode object) mode)
Arguments:
object -- a gtk:text-view widget
mode -- a value of the gtk:wrap-mode enumeration
Details:
Accessor of the wrap-mode slot of the gtk:text-view class. The gtk:text-view-wrap-mode function gets the line wrapping for the text view. The (setf gtk:text-view-wrap-mode) function sets the line wrapping.
See also:
2024-7-4
Function gtk:text-view-new ()
Returns:
The new gtk:text-view widget.
Details:
Creates a new text view. If you do not call the gtk:text-view-buffer function before using the text view, an empty default text buffer will be created for you. Get the text buffer with the gtk:text-view-buffer function. If you want to specify your own text buffer, consider the gtk:text-view-new-with-buffer function.
See also:
2024-7-4
Function gtk:text-view-new-with-buffer (buffer)
Arguments:
buffer -- a gtk:text-buffer object
Returns:
The new gtk:text-view widget.
Details:
Creates a new text view displaying the text buffer. One text buffer can be shared among many widgets. The buffer argument may be nil to create a default text buffer, in which case this function is equivalent to the gtk:text-view-new function.
See also:
2024-7-4
Function gtk:text-view-scroll-to-mark (view mark &key margin xalign yalign)
Arguments:
view -- a gtk:text-view widget
mark -- a gtk:text-mark object
margin -- a double float margin as a [0.0, 0.5) fraction of screen size
xalign -- a double float with the horizontal alignment of the mark within visible area
yalign -- a double float with the vertical alignment of the mark within visible area
Details:
Scrolls the text view so that the mark is on the screen in the position indicated by the xalign and yalign arguments. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If you do not pass a value for the xalign and yalign arguments, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size margin.
Notes:
The double float arguments take any number. The numbers are coerced to double floats.
See also:
#2024-7-4
Function gtk:text-view-scroll-to-iter (view iter &key margin xalign yalign)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
margin -- a double float margin as a [0.0, 0.5) fraction of screen size
xalign -- a double float with the horizontal alignment of the mark within visible area
yalign -- a double float with the vertical alignment of the mark within visible area
Returns:
True if scrolling occurred.
Details:
Scrolls the text view so that the iterator is on the screen in the position indicated by the xalign and yalign arguments. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If you do not pass a value for the xalign and yalign arguments, the text scrolls the minimal distance to get the iterator onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size margin.

Note that this function uses the currently computed height of the lines in the text buffer. Line heights are computed in an idle handler. So this function may not have the desired effect if it is called before the height computations. To avoid oddness, consider using the gtk:text-view-scroll-to-mark function which saves a point to be scrolled to after line validation.
Notes:
The double float arguments take any number. The numbers are coerced to double floats.
See also:
#2024-7-4
Function gtk:text-view-scroll-mark-onscreen (view mark)
Arguments:
view -- a gtk:text-view widget
mark -- a gtk:text-mark object in the text buffer for the text view
Details:
Scrolls the text view the minimum distance such that the mark is contained within the visible area of the widget.
See also:
2024-7-4
Function gtk:text-view-move-mark-onscreen (view mark)
Arguments:
view -- a gtk:text-view widget
mark -- a gtk:text-mark object
Returns:
True if the mark moved, was not already onscreen.
Details:
Moves a the mark within the text buffer so that it is located within the currently visible text area.
See also:
#2024-7-4
Function gtk:text-view-place-cursor-onscreen (view)
Arguments:
view -- a gtk:text-view widget
Returns:
True if the cursor had to be moved.
Details:
Moves the cursor to the currently visible region of the text buffer, if it is not there already.
See also:
#2024-7-4
Function gtk:text-view-visible-rect (view)
Arguments:
view -- a gtk:text-view widget
Returns:
The gdk:rectangle instance with the current visible region.
Details:
The currently visible region of the text buffer, in text buffer coordinates. Convert to window coordinates with the gtk:text-view-buffer-to-window-coords function.
See also:
#2024-7-4
Function gtk:text-view-iter-location (view iter)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
Returns:
The gdk:rectangle instance with the bounds of the character at iter.
Details:
Gets a rectangle which roughly contains the coordinates of the character at the position of the iterator. The rectangle position is in text buffer coordinates. Use the gtk:text-view-buffer-to-window-coords function to convert these coordinates to coordinates for one of the windows in the text view.
See also:
#2024-7-4
Function gtk:text-view-cursor-locations (view iter)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
Returns:
strong -- a gdk:rectangle instance with the strong cursor position
weak -- a gdk:rectangle instance with the weak cursor position
Details:
Given an iterator within a text layout, determine the positions of the strong and weak cursors if the insertion point is at that iterator. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the paragraph are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the paragraph are inserted.

If the iter argument is nil, the actual cursor position is used.

Note that if the iter argument happens to be the actual cursor position, and there is currently an IM preedit sequence being entered, the returned locations will be adjusted to account for the offset of the preedit cursor within the preedit sequence.

The rectangle position is in text buffer coordinates. Use the gtk:text-view-buffer-to-window-coords function to convert these coordinates to coordinates for one of the windows in the text view.
See also:
#2024-7-4
Function gtk:text-view-line-at-y (view y)
Arguments:
view -- a gtk:text-view widget
y -- an integer with the y coordinate
Returns:
iter -- a gtk:text-iter iterator
line -- an integer with the top coordinate of the line
Details:
Gets the gtk:text-iter iterator at the start of the line containing the coordinate y. The y argument is in text buffer coordinates, convert from window coordinates with the gtk:text-view-window-to-buffer-coords function. If non-nil, line will be filled with the coordinate of the top edge of the line.
See also:
#2024-7-4
Function gtk:text-view-line-yrange (view iter)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
Returns:
y -- an integer with the y coordinate
height -- an integer with the height
Details:
Gets the y coordinate of the top of the line containing iter, and the height of the line. The coordinate is a text buffer coordinate. Convert to window coordinates with the gtk:text-view-buffer-to-window-coords function.
See also:
#2024-7-4
Function gtk:text-view-iter-at-location (view x y)
Arguments:
view -- a gtk:text-view widget
x -- an integer with the x position, in text buffer coordinates
y -- an integer with the y position, in text buffer coordinates
Returns:
The gtk:text-iter iterator at text buffer coordinates.
Details:
Retrieves the iterator at text buffer coordinates x and y. Text buffer coordinates are coordinates for the entire text buffer, not just the currently displayed portion. If you have coordinates from an event, you have to convert those to text buffer coordinates with the gtk:text-view-window-to-buffer-coords function.
See also:
2024-7-4
Function gtk:text-view-iter-at-position (view x y)
Arguments:
view -- a gtk:text-view widget
x -- an integer with the x position, in text buffer coordinates
y -- an integer with the y position, in text buffer coordinates
Returns:
iter -- a gtk:text-iter iterator
trailing -- if non-nil, an integer indicating where in the grapheme the user clicked, it will either be zero, or the number of characters in the grapheme, 0 represents the trailing edge of the grapheme
Details:
Retrieves the iterator pointing to the character at text buffer coordinates x and y. Text buffer coordinates are coordinates for the entire text buffer, not just the currently displayed portion. If you have coordinates from an event, you have to convert those to text buffer coordinates with the gtk:text-view-window-to-buffer-coords function.

Note that this is different from the gtk:text-view-iter-at-location function, which returns cursor locations, that is, positions between characters.
See also:
#2024-7-4
Function gtk:text-view-buffer-to-window-coords (view wtype xbuffer ybuffer)
Arguments:
view -- a gtk:text-view widget
wtype -- a gtk:text-window-type value, except :private
xbuffer -- an integer with the text buffer x coordinate
ybuffer -- an integer with the text buffer y coordinate
Returns:
xwindow -- an integer with the window x coordinate
ywindow -- an integer with the window y coordinate
Details:
Converts the text buffer coordinates to window coordinates.
See also:
#2024-7-4
Function gtk:text-view-window-to-buffer-coords (view wtype xwindow ywindow)
Arguments:
view -- a gtk:text-view widget
wtype -- a gtk:text-window-type value, except :private
xwindow -- an integer with the window x coordinate
ywindow -- an integer with the window y coordinate
Returns:
xbuffer -- an integer with the text buffer x coordinate or
ybuffer -- an integer with the text buffer y coordinate
Details:
Converts coordinates on the window identified by wtype to text buffer coordinates.
See also:
2024-7-4
Function gtk:text-view-move-display-line (view iter &key direction start-or-end)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
direction -- a :forward or :backward keyword value, the default value is :forward
start-or-end -- true to go the end of the next or the start of the previous display line, the default value is false
Returns:
True if iter was moved and is not on the end iterator.
Details:
Moves the given iter by one display (wrapped) line. If the direction argument is :forward moves forward otherwise backward. If the start-or-end argument is true moves to next display line end for a forward move and to the display line start for a backward move.

A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the width of the text view. Paragraphs are the same in all text views, since they depend on the contents of the text buffer.
Notes:
This function combines the gtk_text_view_forward_display_line (), gtk_text_view_forward_display_line_end(), gtk_text_view_backward_display_line(), and gtk_text_view_backward_display_line_start() functions into one Lisp function.
See also:
#2024-7-4
Function gtk:text-view-starts-display-line (view iter)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
Returns:
True if iter begins a wrapped line.
Details:
Determines whether iter is at the start of a display line. See the gtk:text-view-forward-display-line function for an explanation of display lines versus paragraphs.
See also:
gtk:text-view
gtk:text-iter
gtk:text-view-forward-display-line
#2024-7-4
Function gtk:text-view-move-visually (view iter count)
Arguments:
view -- a gtk:text-view widget
iter -- a gtk:text-iter iterator
count -- an integer with the number of characters to move, negative moves left, positive moves right
Returns:
True if iter moved and is not on the end iterator.
Details:
Move the iterator a given number of characters visually, treating it as the strong cursor position. If the count argument is positive, then the new strong cursor position will be count positions to the right of the old cursor position. If the count argument is negative then the new strong cursor position will be count positions to the left of the old cursor position.

In the presence of bi-directional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run.
See also:
#2024-7-4
Function gtk:text-view-add-child-at-anchor (view child anchor)
Arguments:
view -- a gtk:text-view widget
child -- a gtk:widget object
anchor -- a gtk:text-child-anchor object in the text buffer for view
Details:
Adds a child widget in the text buffer, at the given anchor.
See also:
2024-7-4
Function gtk:text-view-remove (view child)
Arguments:
view -- a gtk:text-view object
child -- a gtk:widget object to remove
Details:
Removes a child widget from the text view.
See also:
#2024-7-4
Function gtk:text-view-gutter (view wtype)
Syntax:
(gtk:text-view-gutter view win) => widget
(setf (gtk:text-view-gutter view win) widget)
Arguments:
view -- a gtk:text-view widget
wtype -- a gtk:text-window-type value
widget -- a gtk:widget object or nil
Details:
The gtk:text-view-gutter function gets widget that has previously been set. The (setf gtk:text-view-gutter) function places widget into the gutter specified by win.

The wtype argument must be one of the values :left, :right, :top, or :bottom of the gtk:text-window-type enumeration.
See also:
#2024-7-4
Function gtk:text-view-add-overlay (view child xpos ypos)
Arguments:
view -- a gtk:text-view widget
child -- a gtk:widget child widget
xpos -- an integer with the x position of child in window coordinates
ypos -- an integer with the y position of child in window coordinates
Details:
Adds child at a fixed coordinate in the text window of the gtk:text-view widget. The xpos and ypos arguments must be in buffer coordinates. See the gtk:text-view-iter-location function to convert to buffer coordinates.

The child widget will scroll with the text view. If instead you want a widget that will not move with the text view contents see the gtk:overlay widget.
See also:
#2024-7-4
Function gtk:text-view-move-overlay (view child xpos ypos)
Arguments:
view -- a gtk:text-view widget
child -- a gtk:widget child widget already added
xpos -- an integer with the new x position of child in buffer coordinates
ypos -- an integer with the new y position of child in buffer coordinates
Details:
Updates the position of the child widget added with the gtk:text-view-add-overlay function.
See also:
#2024-7-4
Arguments:
view -- a gtk:text-view widget
Details:
Ensures that the cursor is shown, that is, not in an 'off' blink interval, and resets the time that it will stay blinking, or visible, in case blinking is disabled. This function should be called in response to user input, for example, from derived classes that override the "key-press-event" handler of the text view.
See also:
#2024-7-4
Function gtk:text-view-im-context-filter-keypress (view event)
Arguments:
view -- a gtk:text-view widget
event -- a gdk:event key event
Returns:
True if the input method handled the key event.
Details:
Allow the text view input method to internally handle key press and release events. If this function returns true, then no further processing should be done for this key event. See the gtk:im-context-filter-keypress function.

Note that you are expected to call this function from your handler when overriding key event handling. This is needed in the case when you need to insert your own key handling between the input method and the default key event handling of the text view.
static gboolean
gtk_foo_bar_key_press_event (GtkWidget   *widget,
                             GdkEventKey *event)
{
  if ((key->keyval == GDK_KEY_Return || key->keyval == GDK_KEY_KP_Enter))
    {
      if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (view),
                                                    event))
        return TRUE;
    }

/* Do some stuff */

return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class) ->key_press_event (widget, event); }
See also:
#2024-7-4
Function gtk:text-view-reset-im-context (view)
Arguments:
view -- a gtk:text-view widget
Details:
Reset the input method context of the text view if needed. This can be necessary in the case where modifying the text buffer would confuse on-going input method behavior.
See also:
#2024-7-4
Function gtk:text-view-ltr-context (view)
Arguments:
view -- a gtk:text-view widget
Returns:
The pango:context object.
Details:
Gets the Pango context that is used for rendering LTR directed text layouts. The context may be replaced when CSS changes occur.

Since 4.4
See also:
#2024-7-4
Function gtk:text-view-rtl-context (view)
Arguments:
view -- a gtk:text-view widget
Returns:
The pango:context object.
Details:
Gets the Pango context that is used for rendering RTL directed text layouts. The context may be replaced when CSS changes occur.

Since 4.4
See also:
#2024-7-4

Popovers

GtkPopover

Class gtk:popover
Superclasses:
Documented Subclasses:
Direct Slots:
autohide
The autohide property of type :boolean (Read / Write)
Whether to dismiss the popover on outside clicks.
Default value: true
cascade-popdown
The cascade-popdown property of type :boolean (Read / Write)
Whether the popover pops down after a child popover.
Default value: false
child
The child property of type gtk:widget (Read / Write)
The child widget.
default-widget
The default-widget property of type gtk:widget (Read / Write)
The default widget.
has-arrow
The has-arrow property of type :boolean (Read / Write)
Whether to draw an arrow.
Default value: true
mnemonics-visible
The mnemonics-visible property of type :boolean (Read / Write)
Whether mnemonics are currently visible in this popover.
Default value: false
pointing-to
The pointing-to property of type gdk:rectangle (Read / Write)
Marks a specific rectangle to be pointed.
position
The position property of type gtk:position-type (Read / Write)
Sets the preferred position of the popover.
Default value: :top
Returned by:
Slot Access Functions:
Details:
The gtk:popover widget is a bubble-like context window, primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. By default, they point to the whole widget area, although this behavior can be changed with the gtk:popover-pointing-to function.

Figure: GtkPopover

The position of a popover relative to the widget it is attached to can also be changed through the gtk:popover-position function.

By default, the gtk:popover widget performs a GTK grab, in order to ensure input events get redirected to it while it is shown, and also so the popover is dismissed in the expected situations, clicks outside the popover, or the Escape key being pressed. If no such modal behavior is desired on a popover, the gtk:popover-autohide function may be called on it to tweak its behavior.

GtkPopover as menu replacement
The gtk:popover widget is often used to replace menus. The best was to do this is to use the gtk:popover-menu subclass which supports being populated from a g:menu-model object with the gtk:popover-menu-new-from-model function.
Examples:
<section>
  <attribute name="display-hint">horizontal-buttons</attribute>
  <item>
    <attribute name="label">Cut</attribute>
    <attribute name="action">app.cut</attribute>
    <attribute name="verb-icon">edit-cut-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Copy</attribute>
    <attribute name="action">app.copy</attribute>
    <attribute name="verb-icon">edit-copy-symbolic</attribute>
  </item>
  <item>
    <attribute name="label">Paste</attribute>
    <attribute name="action">app.paste</attribute>
    <attribute name="verb-icon">edit-paste-symbolic</attribute>
  </item>
</section>    
CSS nodes:
The contents child node always gets the .background style class and the popover itself gets the .menu style class if the popover is menu-like, that is a gtk:popover-menu widget.

Particular uses of the gtk:popover widget, such as touch selection popups or magnifiers in gtk:entry or gtk:text-view widgets get style classes like .touch-selection or .magnifier to differentiate from plain popovers.

When styling a popover directly, the popover node should usually not have any background. The visible part of the popover can have a shadow. To specify it in CSS, set the box-shadow of the contents node.

Note that, in order to accomplish appropriate arrow visuals, the gtk:popover widget uses custom drawing for the arrow node. This makes it possible for the arrow to change its shape dynamically, but it also limits the possibilities of styling it using CSS. In particular, the arrow gets drawn over the content node's border so they look like one shape, which means that the border-width of the content node and the arrow node should be the same. The arrow also does not support any border shape other than solid, no border-radius, only one border width, border-bottom-width is used, and no box-shadow.
Signal Details:
The "activate-default" signal
lambda (popover)    :action      
popover
The gtk:popover widget which received the signal.
The signal is a keybinding signal which gets emitted when the user activates the default widget of the popover.
The "closed" signal
lambda (popover)    :run-last      
popover
The gtk:popover widget which received the signal.
The signal is emitted when the popover is dismissed either through API or user interaction.
See also:
2024-10-26
Accessor gtk:popover-autohide (object)
Syntax:
(gtk:popover-autohide object) => setting
(setf (gtk:popover-autohide object) setting)
Arguments:
object -- a gtk:popover widget
setting -- a boolean whether to dismiss the popover on outside clicks
Details:
Accessor of the autohide slot of the gtk:popover class. The gtk:popover-autohide function returns whether the popover is modal. The (setf gtk:popover-autohide) function sets whether popover is modal.

A modal popover will grab the keyboard focus on it when being displayed. Clicking outside the popover area or pressing the Esc key will dismiss the popover.

Called this function on an already showing popup with a new autohide value different from the current one, will cause the popup to be hidden.
See also:
2024-10-26
Accessor gtk:popover-cascade-popdown (object)
Syntax:
(gtk:popover-cascade-popdown object) => setting
(setf (gtk:popover-cascade-popdown object) setting)
Arguments:
object -- a gtk:popover widget
setting -- a boolean whether the popover should follow a child closing
Details:
Accessor of the cascade-popdown slot of the gtk:popover class. The gtk:popover-cascade-popdown function returns whether the popover will close after a modal child is closed. If true, the popover will be closed when a child modal popover is closed. If false, the popover will stay visible.
See also:
2024-10-26
Accessor gtk:popover-child (object)
Syntax:
(gtk:popover-child object) => child
(setf (gtk:popover-child object) child)
Arguments:
object -- a gtk:popover widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:popover class. The gtk:popover-child function gets the child widget of the popover. The (setf gtk:popover-child) function sets the child widget.
See also:
2024-10-26
Accessor gtk:popover-default-widget (object)
Syntax:
(gtk:popover-default-widget object) => widget
(setf (gtk:popover-default-widget object) widget)
Arguments:
object -- a gtk:popover widget
widget -- a gtk:widget default widget, or nil to unset the default widget
Details:
Accessor of the default-widget slot of the gtk:popover class. The gtk:popover-default-widget function gets the default widget of the popover. The (setf gtk:popover-default-widget) function sets or unsets the default widget.

The default widget is the widget that is activated when the user presses the Enter key in a dialog, for example.
See also:
2024-10-26
Accessor gtk:popover-has-arrow (object)
Syntax:
(gtk:popover-has-arrow object) => setting
(setf (gtk:popover-has-arrow object) setting)
Arguments:
object -- a gtk:popover widget
setting -- a boolean whether the popover has an arrow
Details:
Accessor of the has-arrow slot of the gtk:popover class. The gtk:popover-has-arrow function gets whether the popover is showing an arrow pointing at the widget that it is relative to. The (setf gtk:popover-has-arrow) function sets whether the popover should draw an arrow.
See also:
2024-10-26
Accessor gtk:popover-mnemonics-visible (object)
Syntax:
(gtk:popover-mnemonics-visible object) => setting
(setf (gtk:popover-mnemonics-visible object) setting)
Arguments:
object -- a gtk:popover widget
setting -- a boolean whether mnemonics are currently visible in the popover
Details:
Accessor of the mnemonics-visible slot of the gtk:popover class. Whether mnemonics are currently visible in this popover.
See also:
2024-10-26
Accessor gtk:popover-pointing-to (object)
Syntax:
(gtk:popover-pointing-to object) => rect
(setf (gtk:popover-pointing-to object) rect)
Arguments:
object -- a gtk:popover widget
rect -- a gdk:rectangle instance to point to
Details:
Accessor of the pointing-to slot of the gtk:popover class. The gtk:popover-pointing-to function gets the rectangle that the popover points to. The (setf gtk:popover-pointing-to) function sets the rectangle that popover points to. This is in the coordinate space of the popover parent.
See also:
2024-10-26
Accessor gtk:popover-position (object)
Syntax:
(gtk:popover-pointing-to object) => position
(setf (gtk:popover-pointing-to object) position)
Arguments:
object -- a gtk:popover widget
position -- a gtk:position-type value with the preferred popover position
Details:
Accessor of the position slot of the gtk:popover class. The gtk:popover-position function returns the preferred position of the popover to appear. The (setf gtk:popover-position) function sets the preferred position. If the popover is currently visible, it will be immediately updated.

This preference will be respected where possible, although on lack of space, for example, if close to the window edges, the gtk:popover widget may choose to appear on the opposite side.
See also:
2024-10-26
Function gtk:popover-new ()
Returns:
The new gtk:popover widget.
Details:
Creates a new popover.
See also:
2024-10-26
Function gtk:popover-popup (popover)
Arguments:
popover -- a gtk:popover widget
Details:
Pops the popover up.
See also:
#2024-10-26
Function gtk:popover-popdown (popover)
Arguments:
popover -- a gtk:popover widget
Details:
Pops the popover down. This may have the side-effect of closing a parent popover as well. See the cascade-popdown property.
See also:
#2024-10-26
Function gtk:popover-present (popover)
Arguments:
popover -- a gtk:popover widget
Details:
Allocate a size for the gtk:popover widget. This function needs to be called in size-allocate by widgets who have a gtk:popover widget as child. When using a layout manager, this is happening automatically.

To make a popover appear on screen, use the gtk:popover-popup function.
See also:
#2024-10-26
Function gtk:popover-offset (popover)
Syntax:
(gtk:popover-offset popover) => xoffset, yoffset
(setf (gtk:popover-offset popover) '(xoffset yoffset))
Arguments:
popover -- a gtk:popover widget
xoffset -- an integer with the xoffset
yoffset -- an integer with the yoffset
Details:
The gtk:popover-offset function gets the offset to use when calculating the position of the popover. The (setf gtk:popover-offset) function sets the offset. These values are used when preparing the gdk:popup-layout object for positioning the popover.
See also:
#2024-10-26

GtkPopoverMenu

GFlags gtk:popover-menu-flags
Declaration:
(gobject:define-gflags "GtkPopoverMenuFlags" popover-menu-flags
  (:export t
   :type-initializer "gtk_popover_menu_flags_get_type")
  (:none 0)
  (:nested #.(ash 1 0)))  
Values:
:sliding
Submenus are presented as sliding submenus that replace the main menu. Since 4.14
:nested
Create submenus as nested popovers. Without this flag, submenus are created as sliding pages that replace the main menu.
Details:
Flags that affect how popover menus built from a g:menu-model object are created and displayed.
See also:
2024-10-26
Class gtk:popover-menu
Superclasses:
Documented Subclasses:
None
Direct Slots:
flags
The flags property of type gtk:popover-menu-flags (Read / Write)
The flags that popover uses to create/display a menu from its model. If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild. Since 4.14
Default value: :sliding
menu-model
The menu-model property of type g:menu-model (Read / Write)
The model from which the menu is made.
visible-submenu
The visible-submenu property of type :string (Read / Write)
The name of the visible submenu.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:popover-menu class is a subclass of the gtk:popover class that treats its children like menus and allows switching between them. It can open submenus as traditional, nested submenus, or in a more touch-friendly sliding fashion.

Figure: GtkPopoverMenu

The gtk:popover-menu widget is meant to be used primarily with menu models, using the gtk:popover-menu-new-from-model function. If you need to put other widgets such as gtk:spin-button or gtk:switch widgets into a popover, use a plain gtk:popover widget.

Menu models
The XML format understood by the gtk:builder object for the g:menu-model object consists of a toplevel <menu> element, which contains one or more <item> elements. Each <item> element contains <attribute> and <link> elements with a mandatory name attribute. <link> elements have the same content model as <menu>. Instead of <link name="submenu"> or <link name="section">, you can use <submenu> or <section> elements.
<menu id='app-menu'>
  <section>
    <item>
      <attribute name='label' translatable='yes'>_New Window</attribute>
      <attribute name='action'>app.new</attribute>
    </item>
    <item>
      <attribute name='label' translatable='yes'>_About Sunny</attribute>
      <attribute name='action'>app.about</attribute>
    </item>
    <item>
      <attribute name='label' translatable='yes'>_Quit</attribute>
      <attribute name='action'>app.quit</attribute>
    </item>
  </section>
</menu>  
Attribute values can be translated using GNU gettext, like other GtkBuilder content. <attribute> elements can be marked for translation with a translatable="yes" attribute. It is also possible to specify message context and translator comments, using the context and comments attributes. To make use of this, the GtkBuilder must have been given the GNU gettext domain to use.

The following attributes are used when constructing menu items:
"label"
a user-visible string to display
"action"
the prefixed name of the action to trigger
"target"
the parameter to use when activating the action
"icon", "verb-icon"
names of icons that may be displayed
"submenu-action"
name of an action that may be used to determine if a submenu can be opened
"hidden-when"
a string used to determine when the item will be hidden. Possible values include "action-disabled", "action-missing", "macos-menubar". This is mainly useful for exported menus, see the gtk:application-menubar function.
"custom"
a string used to match against the ID of a custom child added with the gtk:popover-menu-add-child, gtk:popover-menu-bar-add-child functions, or in the UI file with <child type="ID">.
The following attributes are used when constructing sections:
"label"
a user-visible string to use as section heading
"display-hint"
a string used to determine special formatting for the section. Possible values include "horizontal-buttons", "circular-buttons" and "inline-buttons". They all indicate that section should be displayed as a horizontal row of buttons.
"text-direction"
a string used to determine the GtkTextDirection to use when "display-hint" is set to "horizontal-buttons". Possible values include "rtl", "ltr", and "none".
The following attributes are used when constructing submenus:
"label"
a user-visible string to display
"icon"
icon name to display
Menu items will also show accelerators, which are usually associated with actions via the gtk:application-accels-for-action, gtk:widget-class-add-binding-action or gtk:shortcut-controller-add-shortcut functions.
CSS nodes:
The gtk:popover-menu implementation is just a subclass of the gtk:popover class that adds custom content to it, therefore it has the same CSS nodes. It is one of the cases that add a .menu style class to the popover's main node.
Accessibility:
The gtk:popover-menu implementation uses the :menu role of the gtk:accessible-role enumeration, and its items use the :menu-item, :menu-item-checkbox role or menu-item-radio roles, depending on the action they are connected to.
See also:
2024-10-26
Accessor gtk:popover-menu-flags (object)
Syntax:
(gtk:popover-menu-flags object) => flags
(setf (gtk:popover-menu-flags object) flags)
Arguments:
object -- a gtk:popover-menu widget
flags -- a gtk:popover-menu-flags value
Details:
Accessor of the flags slot of the gtk:popover-menu class. The gtk:popover-menu-flags function returns the flags that popover uses to create/display a menu from its model. The (setf gtk:popover-menu-flags) function sets the flags that popover uses.

If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild.

Since 4.14
See also:
2024-5-26
Accessor gtk:popover-menu-menu-model (object)
Syntax:
(gtk:popover-menu-menu-model object) => model
(setf (gtk:popover-menu-menu-model object) model)
Arguments:
object -- a gtk:popover-menu widget
model -- a g:menu-model object
Details:
Accessor of the menu-model slot of the gtk:popover-menu class. The gtk:popover-menu-menu-model function returns the menu model used to populate the popover. The (setf gtk:popover-menu-menu-model) function sets the menu model. The existing contents of the popover are removed, and the popover is populated with new contents according to the menu model.
See also:
2024-5-26
Accessor gtk:popover-menu-visible-submenu (object)
Syntax:
(gtk:popover-menu-visible-submenu object) => submenu
(setf (gtk:popover-menu-visible-submenu object) submenu)
Arguments:
object -- a gtk:popover-menu widget
submenu -- a string with the name of the submenu
Details:
Accessor of the visible-submenu slot of the gtk:popover-menu class. The name of the visible submenu.
See also:
2024-5-26
Function gtk:popover-menu-new-from-model (model)
Arguments:
model -- a g:menu-model object, or nil
Returns:
The new gtk:popover-menu widget.
Details:
Creates a popover menu and populates it according to the menu model. The created buttons are connected to actions found in the gtk:application-window widget to which the popover belongs - typically by means of being attached to a widget that is contained within the widget hierarchy of the application window. Actions can also be added using the gtk:widget-insert-action-group function on the menus attach widget or on any of its parent widgets.

This function creates menus with sliding submenus. See the gtk:popover-menu-new-from-model-full function for a way to control this.
See also:
#2024-10-26
Function gtk:popover-menu-new-from-model-full (model flags)
Arguments:
model -- a g:menu-model object, or nil
flags -- a gtk:popover-menu-flags value, that affect hwo the menu is created
Returns:
The new gtk:popover-menu widget.
Details:
Creates a popover menu and populates it according to the menu model. The created buttons are connected to actions found in the action groups that are accessible from the parent widget. This includes the gtk:application-window widget to which the popover belongs. Actions can also be added using the gtk:widget-insert-action-group function on the parent widget or on any of its parent widgets.
See also:
#2024-10-26
Function gtk:popover-menu-add-child (popover child id)
Arguments:
popover -- a gtk:popover-menu widget
child -- a gtk:widget child widget to add
id -- a string with the ID to insert the child widget at
Returns:
True if the ID was found and the child widget added.
Details:
Adds a custom widget to a generated menu. For this to work, the menu model of the popover must have an item with a custom attribute that matches the ID.
See also:
#2024-10-26
Function gtk:popover-menu-remove-child (popover child)
Arguments:
popover -- a gtk:popover-menu widget
child -- a gtk:widget child widget
Returns:
True if the child widget was removed.
Details:
Removes a widget that has previously been added with the gtk:popover-menu-add-child function.
See also:
#2024-10-26

GtkPopoverMenuBar

Class gtk:popover-menu-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
menu-model
The menu-model property of type g:menu-model (Read / Write)
The model from which the menu bar is created. The model should only contain submenus as toplevel elements.
Returned by:
Slot Access Functions:
Details:
The gtk:popover-menu-bar widget presents a horizontal bar of items that pop up popover menus when clicked. The only way to create instances of the gtk:popover-menu-bar widget is from a g:menu-model object.

Figure: GtkPopoverMenuBar
CSS nodes:
menubar
├── item[.active]
┊   ╰── popover
╰── item
    ╰── popover    
The gtk:popover-menu-bar implementation has a single CSS node with name menubar, below which each item has its CSS node, and below that the corresponding popover. The item whose popover is currently open gets the .active style class.
Accessibility:
The gtk:popover-menu-bar implementation uses the :menu-bar role of the gtk:accessible-role enumeration. The menu items use the :menu-item role and the menus use the :menu role.
See also:
2024-10-26
Accessor gtk:popover-menu-bar-menu-model (object)
Syntax:
(gtk:popover-menu-bar-menu-model object) => model
(setf (gtk:popover-menu-bar-menu-model object) model)
Arguments:
object -- a gtk:popover-menu widget
model -- a g:menu-model object
Details:
Accessor of the menu-model slot of the gtk:popover-menu class. The gtk:popover-menu-bar-menu-model function returns the model from which the contents of the menu bar are taken. The (setf gtk:popover-menu-bar-menu-model) function sets a menu model.
See also:
2024-10-26
Function gtk:popover-menu-bar-new-from-model (model)
Arguments:
model -- a g:menu-model object, or nil
Returns:
The new gtk:popover-menu-bar widget.
Details:
Creates a gtk:popover-menu-bar widget from a g:menu-model object.
See also:
#2024-10-26
Function gtk:popover-menu-bar-add-child (menubar child id)
Arguments:
menubar -- a gtk:popover-menu-bar widget
child -- a gtk:widget object to add
id -- a string with the ID to insert child at
Returns:
True if the ID was found and the widget added.
Details:
Adds a custom widget to a generated menu bar. For this to work, the menu model of the menu bar must have an item with a custom attribute that matches the ID.
See also:
#2024-10-26
Function gtk:popover-menu-bar-remove-child (menubar child)
Arguments:
menubar -- a gtk:popover-menu-bar widget
child -- a gtk:widget object to remove
Returns:
True if the widget was removed.
Details:
Removes a widget that has previously been added with the gtk:popover-menu-bar-add-child function.
See also:
#2024-10-26

Selector Widgets and Dialogs

GtkColorDialog

Class gtk:color-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
modal
The modal property of type :boolean (Read / Write)
Whether the color chooser dialog is modal.
Default value: true
title
The title property of type :string (Read / Write)
A title that may be shown on the color chooser dialog that is presented by the gtk:color-dialog-choose-rgba function.
Default value: nil
with-alpha
The with-alpha property of type :boolean (Read / Write)
Whether colors may have alpha (translucency). When with-alpha is false, the color that is selected will be forced to have alpha = 1.
Default value: true
Returned by:
Slot Access Functions:
Details:
A gtk:color-dialog object collects the arguments that are needed to present a color chooser dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the gtk:color-dialog-choose-rgba function. This API follows the GIO async pattern, and the result can be obtained by calling the gtk:color-dialog-choose-rgba-finish function.

See the gtk:color-dialog-button widget for a convenient control that uses the gtk:color-dialog object and presents the results.

Since 4.10
See also:
2023-7-28
Accessor gtk:color-dialog-modal (object)
Syntax:
(gtk:color-dialog-modal object) => modal)
(setf (gtk:color-dialog-modal object) modal)
Arguments:
object -- a gtk:color-dialog object
modal -- a boolean whether the color chooser dialog is modal
Details:
Accessor of the modal slot of the gtk:color-dialog class. The gtk:color-dialog-modal function returns whether the color chooser dialog blocks interaction with the parent window while it is presented. The (setf gtk:color-dialog-modal) function sets the property.

Since 4.10
See also:
2023-7-28
Accessor gtk:color-dialog-title (object)
Syntax:
(gtk:color-dialog-title object) => title)
(setf (gtk:color-dialog-title object) title)
Arguments:
object -- a gtk:color-dialog object
title -- a string with the title
Details:
Accessor of the title slot of the gtk:color-dialog class. The gtk:color-dialog-title function returns the title that will be shown on the color chooser dialog. The (setf gtk:color-dialog-title) function sets the title.

Since 4.10
See also:
2023-7-28
Accessor gtk:color-dialog-with-alpha (object)
Syntax:
(gtk:color-dialog-with-alpha object) => setting)
(setf (gtk:color-dialog-with-alpha object) setting)
Arguments:
object -- a gtk:color-dialog object
setting -- a boolean whether colors may have alpha
Details:
Accessor of the with-alpha slot of the gtk:color-dialog class. The gtk:color-dialog-with-alpha function returns whether colors may have alpha. The (setf gtk:color-dialog-with-alpha) function sets the property.

Since 4.10
See also:
2023-7-28
Function gtk:color-dialog-new ()
Returns:
The new gtk:color-dialog object.
Details:
Creates a new gtk:color-dialog object.

Since 4.10
See also:
2023-7-28
Function gtk:color-dialog-choose-rgba (dialog parent color cancellable func)
Arguments:
dialog -- a gtk:color-dialog object
parent -- a parent gtk:window widget
color -- a gdk:rgba instance with the color to select initially
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function initiates a color choice operation by presenting a color chooser dialog to the user. The callback function will be called when the dialog is dismissed. It should call the gtk:color-dialog-choose-rgba-finish function to obtain the result.

Since 4.10
See also:
#2023-7-28
Function gtk:color-dialog-choose-rgba-finish (dialog result)
Arguments:
dialog -- a gtk:color-dialog object
result -- a g:async-result instance
Returns:
The gdk:rgba instance with the selected color, or nil.
Details:
Finishes the gtk:color-dialog-choose-rgba function call and returns the resulting color.

Since 4.10
See also:
#2024-11-21

GtkColorDialogButton

Class gtk:color-dialog-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
dialog
The dialog property of type gtk:color-dialog (Read / Write)
The gtk:color-dialog object that contains parameters for the color chooser dialog.
rgba
The rgba property of type gdk:rgba (Read / Write)
The selected color. This property can be set to give the button its initial color, and it will be updated to reflect the users choice in the color chooser dialog. Listen to the "notify::rgba" signal to get informed about changes to the buttons color.
Default value: #s(gdk:rgba :red 0.0 :green 0.0 :blue 0.0 :alpha 0.0)
Details:
The gtk:color-dialog-button widget is a wrapped around a gtk:color-dialog object and allows to open a color chooser dialog to change the color.

Figure: GtkColorDialogButton

It is a suitable widget for selecting a color in a preference dialog.

Since 4.10
CSS nodes:
colorbutton
╰── button.color
    ╰── [content]    
The gtk:color-dialog-button implementation has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain gtk:button widget, it gets the .color style class.
Signals:
The "activate" signal
lambda (button)    :action      
Emitted when the color dialog button is activated. The signal is an action signal and emitting it causes the button to pop up its dialog. The signal can be directly emitted on objects from user code. Since 4.14
See also:
2023-11-4
Accessor gtk:color-dialog-button-dialog (object)
Syntax:
(gtk:color-dialog-button-dialog object) => dialog
(setf (gtk:color-dialog-button-dialog object) dialog)
Arguments:
object -- a gtk:color-dialog-button object
dialog -- a gtk:color-dialog object
Details:
Accessor of the dialog slot of the gtk:color-dialog-button class. The gtk:color-dialog-button-dialog function returns the gtk:color-dialog object. The (setf gtk:color-dialog-button-dialog) function sets a gtk:color-dialog object to use for creating the color chooser dialog that is presented when the user clicks the button.

Since 4.10
See also:
2023-7-28
Accessor gtk:color-dialog-button-rgba (object)
Syntax:
(gtk:color-dialog-button-rgba object) => rgba
(setf (gtk:color-dialog-button-rgba object) rgba)
Arguments:
object -- a gtk:color-dialog-button object
rgba -- a gdk:rgba instance
Details:
Accessor of the rgba slot of the gtk:color-dialog-button class. The gtk:color-dialog-button-rgba function returns the color of the button. The (setf gtk:color-dialog-button-rgba) function sets the color.

This function is what should be used to obtain the color that was chosen by the user. To get informed about changes, listen to the "notify::color" signal.

Since 4.10
See also:
2023-7-28
Function gtk:color-dialog-button-new (&optional dialog)
Arguments:
dialog -- an optional gtk:color-dialog object to use
Returns:
The new gtk:color-dialog-button widget.
Details:
Creates a new gtk:color-dialog-button widget with the given dialog. You can pass nil to this function and set a gtk:color-dialog object later. The button will be insensitive until that happens.
See also:
2023-7-28

GtkFileDialog

Class gtk:file-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accept-label
The accept-label property of type :string (Read / Write)
Label for the accept button of the file dialog.
default-filter
The default-filter property of type gtk:file-filter (Read / Write)
The default filter, that is, the filter that is initially active in the file chooser dialog. If the default filter is nil, the first filter of the filters property is used as the default filter. If that property contains no filter, the dialog will be unfiltered. If the filters property is not nil, the default filter should be part of the list. If it is not, the dialog may choose to not make it available.
filters
The filters property of type g:list-model (Read / Write)
The list of filters.
initial-file
The initial-file property of type g:file (Read / Write)
The initial file, that is, the file that is initially selected in the file chooser dialog. This is a utility property that sets both initial-folder and initial-name properties.
initial-folder
The initial-folder property of type g:file (Read / Write)
The initial folder, that is, the directory that is initially opened in the file chooser dialog.
initial-name
The initial-name property of type :string (Read / Write)
The initial name, that is, the filename that is initially selected in the file chooser dialog.
modal
The modal property of type :boolean (Read / Write)
Whether the file chooser dialog is modal.
Default value: true
title
The title property of type :string (Read / Write)
A title that may be shown on the file chooser dialog.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:file-dialog object collects the arguments that are needed to present a file chooser dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the gtk:file-dialog-open function, the gtk:file-dialog-save function, etc. These APIs follow the GIO async pattern, and the result can be obtained by calling the corresponding finish function, for example the gtk:file-dialog-open-finish function.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-accept-label (object)
Syntax:
(gtk:file-dialog-accept-label object) => label
(setf (gtk:file-dialog-accept-label object) label)
Arguments:
object -- a gtk:file-dialog object
label -- a string with the accept label
Details:
Accessor of the accept-label slot of the gtk:file-dialog class. The gtk:file-dialog-accept-label function gets the label shown on the accept button of the file chooser dialog. The (setf gtk:file-dialog-accept-label) function sets the label.

Leaving the accept label unset or setting it as nil will fall back to a default label, depending on what API is used to launch the file chooser dialog.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-default-filter (object)
Syntax:
(gtk:file-dialog-default-filter object) => filter
(setf (gtk:file-dialog-default-filter object) filter)
Arguments:
object -- a gtk:file-dialog object
filter -- a gtk:file-filter object
Details:
Accessor of the default-filter slot of the gtk:file-dialog class. The gtk:file-dialog-default-filter function gets the filter that will be selected by default in the file chooser dialog. The (setf gtk:file-dialog-default-filter) function sets the filter.

If set to nil, the first item in filters will be used as the default filter. If that list is empty, the dialog will be unfiltered.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-filters (object)
Syntax:
(gtk:file-dialog-filters object) => filters
(setf (gtk:file-dialog-filters object) filters)
Arguments:
object -- a gtk:file-dialog object
filters -- a g:list-model object with the gtk:file-filter objects
Details:
Accessor of the filters slot of the gtk:file-dialog class. The gtk:file-dialog-filters function gets the filters that will be offered to the user in the file chooser dialog. The (setf gtk:file-dialog-filters) function sets the filters.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-initial-file (object)
Syntax:
(gtk:file-dialog-initial-file object) => file
(setf (gtk:file-dialog-initial-file object) file)
Arguments:
object -- a gtk:file-dialog object
file -- a g:file object with the file
Details:
Accessor of the initial-file slot of the gtk:file-dialog class. The gtk:file-dialog-initial-file function gets the file that will be initially selected in the file chooser dialog. The (setf gtk:file-dialog-initial-file) function sets the file.

This function is a shortcut for calling both the gtk:file-dialog-initial-folder and gtk:file-dialog-initial-name functions with the directory and name of file respectively.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-initial-folder (object)
Syntax:
(gtk:file-dialog-initial-folder object) => folder
(setf (gtk:file-dialog-initial-folder object) folder)
Arguments:
object -- a gtk:file-dialog object
folder -- a g:file object with the folder
Details:
Accessor of the initial-folder slot of the gtk:file-dialog class. The gtk:file-dialog-initial-folder function gets the folder that will be set as the initial folder in the file chooser dialog. The (setf gtk:file-dialog-initial-folder) function sets the folder.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-initial-name (object)
Syntax:
(gtk:file-dialog-initial-name object) => name
(setf (gtk:file-dialog-initial-name object) name)
Arguments:
object -- a gtk:file-dialog object
name -- a string with the name
Details:
Accessor of the initial-name slot of the gtk:file-dialog class. The gtk:file-dialog-initial-name function gets the name for the file that should be initially set. The (setf gtk:file-dialog-initial-name) function sets the name. For saving dialogs, this will usually be pre-entered into the name field.

If a file with this name already exists in the directory set via the initial-folder property, the dialog should preselect it.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-modal (object)
Syntax:
(gtk:file-dialog-modal object) => modal
(setf (gtk:file-dialog-modal object) modal)
Arguments:
object -- a gtk:file-dialog object
modal -- a boolean whether the file chooser dialog is modal
Details:
Accessor of the modal slot of the gtk:file-dialog class. The gtk:file-dialog-modal function returns whether the file chooser dialog blocks interaction with the parent window while it is presented. The (setf gtk:file-dialog-modal) function sets the property.

Since 4.10
See also:
2023-7-22
Accessor gtk:file-dialog-title (object)
Syntax:
(gtk:file-dialog-title object) => title
(setf (gtk:file-dialog-title object) title)
Arguments:
object -- a gtk:file-dialog object
title -- a string with the title
Details:
Accessor of the title slot of the gtk:file-dialog class. The gtk:file-dialog-title function returns the title that will be shown on the file chooser dialog. The (setf gtk:file-dialog-title) function sets the title.

Since 4.10
See also:
2023-7-22
Function gtk:file-dialog-new ()
Returns:
The new gtk:file-dialog object.
Details:
Creates a new file chooser dialog.
See also:
2023-7-22
Function gtk:file-dialog-open (dialog parent cancellable func)
Arguments:
dialog -- a gtk:file-dialog object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation, the argument can be nil
func -- a g:async-ready-callback function to call when the operation is complete, the argument can be nil
Details:
This function initiates a file selection operation by presenting a file chooser dialog to the user. The callback will be called when the dialog is dismissed. It should call the gtk:file-dialog-open-finish function to obtain the result.

Since 4.10
See also:
2023-7-27
Function gtk:file-dialog-open-finish (dialog result)
Arguments:
dialog -- a gtk:file-dialog object
result -- a g:async-result object
Returns:
The g:file object with the file that was selected, otherwise nil.
Details:
Finishes the gtk:file-dialog-open function call and returns the resulting file.

Since 4.10
See also:
2024-11-21
Function gtk:file-dialog-open-multiple (dialog parent cancellable func)
Arguments:
dialog -- a gtk:file-dialog object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation, the argument can be nil
func -- a g:async-ready-callback function to call when the operation is complete, the argument can be nil
Details:
This function initiates a multi-file selection operation by presenting a file chooser dialog to the user. The file chooser will initially be opened in the initial-folder directory. The callback will be called when the dialog is dismissed. It should call the gtk:file-dialog-open-multiple-finish function to obtain the result.

Since 4.10
See also:
#2023-7-22
Function gtk:file-dialog-open-multiple-finish (dialog result)
Arguments:
dialog -- a gtk:file-dialog object
result -- a g:async-result object
Returns:
The g:list-model object with the g:file objects that were selected, otherwise nil.
Details:
Finishes the gtk:file-dialog-open-multiple function call and returns the resulting files in a g:list-model object.

Since 4.10
See also:
#2024-11-21
Function gtk:file-dialog-save (dialog parent cancellable func)
Arguments:
dialog -- a gtk:file-dialog object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation, the argument can be nil
func -- a g:async-ready-callback function to call when the operation is complete, the argument can be nil
Details:
This function initiates a file save operation by presenting a file chooser dialog to the user. The callback will be called when the dialog is dismissed. It should call the gtk:file-dialog-save-finish function to obtain the result.

Since 4.10
See also:
#2023-7-22
Function gtk:file-dialog-save-finish (dialog result)
Arguments:
dialog -- a gtk:file-dialog object
result -- a g:async-result object
Returns:
The g:file object with the file that was selected, otherwise nil.
Details:
Finishes the gtk:file-dialog-save function call and returns the resulting file.

Since 4.10
See also:
#2024-11-21
Function gtk:file-dialog-select-folder (dialog parent cancellable func)
Arguments:
dialog -- a gtk:file-dialog object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation, the argument can be nil
func -- a g:async-ready-callback function to call when the operation is complete, the argument can be nil
Details:
This function initiates a directory selection operation by presenting a file chooser dialog to the user. The file chooser will initially be opened in the initial-folder directory. The callback will be called when the dialog is dismissed. It should call the gtk:file-dialog-select-folder-finish function to obtain the result.

Since 4.10
See also:
#2023-7-22
Function gtk:file-dialog-select-folder-finish (dialog result)
Arguments:
dialog -- a gtk:file-dialog object
result -- a g:async-result object
Returns:
The g:file object with the file that was selected, otherwise nil.
Details:
Finishes the gtk:file-dialog-select-folder function call and returns the resulting folder.

Since 4.10
See also:
#2024-11-21
Function gtk:file-dialog-select-multiple-folders (dialog parent cancellable func)
Arguments:
dialog -- a gtk:file-dialog object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation, the argument can be nil
func -- a g:async-ready-callback function to call when the operation is complete, the argument can be nil
Details:
This function initiates a multi-directory selection operation by presenting a file chooser dialog to the user. The file chooser will initially be opened in the initial-folder directory. The callback will be called when the dialog is dismissed. It should call the gtk:file-dialog-select-multiple-folders-finish function to obtain the result.

Since 4.10
See also:
#2023-7-22
Function gtk:file-dialog-select-multiple-folders-finish (dialog result)
Arguments:
dialog -- a gtk:file-dialog object
result -- a g:async-result object
Returns:
The g:file object with the file that was selected, otherwise nil.
Details:
Finishes the gtk:file-dialog-select-multiple-folders function call and returns the resulting folders in a g:list-model object.

Since 4.10
See also:
#2024-11-21

GtkFileLauncher

Class gtk:file-launcher
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
always-ask
The always-ask property of type :boolean (Read / Write)
Whether to ask the user to choose an application for opening the file. If false, the file might be opened with a default application or the previous choice. Since 4.12
Default value: false
file
The file property of type g:file (Read / Write)
The file to launch. Since 4.10
writable
The writable property of type gboolean (Read / Write)
Whether to make the file writable for the handler. Since 4.14
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:file-launcher object collects the arguments that are needed to open a file with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away.

The operation is started with the gtk:file-launcher-launch function. This API follows the GIO async pattern, and the result can be obtained by calling the gtk:file-launcher-launch-finish function.

To launch uris that do not represent files, use the gtk:uri-launcher class.

Since 4.10
See also:
2024-5-26
Accessor gtk:file-launcher-always-ask (object)
Syntax:
(gtk:file-launcher-always-ask object) => setting
(setf (gtk:file-launcher-always-ask object) setting)
Arguments:
object -- a gtk:file-launcher object
setting -- a boolean whether to always ask the user
Details:
Accessor of the always-ask slot of the gtk:file-launcher class. The gtk:file-launcher-always-ask function returns whether to ask the user to choose an application for opening the file. The (setf gtk:file-launcher-always-ask) function sets whether to always ask the user. If false, the file might be opened with a default application or the previous choice.

Since 4.12
See also:
2024-5-26
Accessor gtk:file-launcher-file (object)
Syntax:
(gtk:file-launcher-file object) => file
(setf (gtk:file-launcher-file object) file)
Arguments:
object -- a gtk:file-launcher object
file -- a g:file object
Details:
Accessor of the file slot of the gtk:file-launcher class. The gtk:file-launcher-file function gets the file that will be opened. The (setf gtk:file-launcher-file) function sets the file.

Since 4.10
See also:
2024-5-26
Accessor gtk:file-launcher-writable (object)
Syntax:
(gtk:file-launcher-writable object) => writable
(setf (gtk:file-launcher-writable object) writable)
Arguments:
object -- a gtk:file-launcher object
writable -- a boolean whether to make the file writable
Details:
Accessor of the writable slot of the gtk:file-launcher class. The gtk:file-launcher-writable function returns whether to make the file writable for the handler. The (setf gtk:file-launcher-writable) function sets whether to make the file writable for the handler.

Since 4.14
See also:
2024-5-26
Function gtk:file-launcher-new (&optional file)
Arguments:
file -- a g:file object
Returns:
The new gtk:file-launcher object
Details:
Creates a new gtk:file-launcher object.

Since 4.10
See also:
#2023-10-12
Function gtk:file-launcher-launch (launcher parent cancellable func)
Arguments:
launcher -- a gtk:file-launcher object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
Launch an application to open the file. This may present an app chooser dialog to the user.

The callback will be called when the operation is completed. It should call the gtk:file-launcher-launch-finish function to obtain the result.

Since 4.10
See also:
#2023-10-12
Function gtk:file-launcher-launch-finish (launcher result)
Arguments:
launcher -- a gtk:file-launcher object
result -- a g:async-result object
Returns:
True if an application was launched, or false on error.
Details:
Finishes the the gtk:file-launcher-launch function call and returns the result.

Since 4.10
See also:
#2024-11-21
Function gtk:file-launcher-open-containing-folder (launcher parent cancellable func)
Arguments:
launcher -- a gtk:file-launcher object
parent -- a gtk:window parent window
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
Launch a file manager to show the file in its parent directory. This is only supported native files. It will fail if file is, for example, a http:// URI.

The callback function will be called when the operation is completed. It should call the gtk:file-launcher-open-containing-folder-finish function to obtain the result.

Since 4.10
See also:
#2023-10-12
Function gtk:file-launcher-open-containing-folder-finish (launcher result)
Arguments:
launcher -- a gtk:file-launcher object
result -- a g:async-result object
Details:
Finishes the gtk:file-launcher-open-containing-folder function call and returns the result.

Since 4.10
See also:
#2024-11-21

GtkUriLauncher

Class gtk:uri-launcher
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
uri
The uri property of type :string (Read / Write)
The URI to launch.
Details:
A gtk:uri-launcher object collects the arguments that are needed to open a URI with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away.

The operation is started with the gtk:uri-launcher-launch function. This API follows the GIO async pattern, and the result can be obtained by calling the gtk:uri-launcher-launch-finish function.

To launch a file, use the gtk:file-launcher object.

Since 4.10
See also:
#2023-10-19
Accessor gtk:uri-launcher-uri (object)
Syntax:
(gtk:uri-launcher-uri object) => uri
(setf (gtk:uri-launcher-uri object) uri)
Arguments:
object -- a gtk:uri-launcher object
uri -- a string with the URI
Details:
Accessor of the uri slot of the gtk:uri-launcher class. The gtk:uri-launcher-uri function gets the URI that will be opened. The (setf gtk:uri-launcher-uri) function sets the URI.

Since 4.10
See also:
#2023-10-12
Function gtk:uri-launcher-new (uri)
Arguments:
uri -- a string with the URI to open
Returns:
The new gtk:uri-launcher object.
Details:
Creates a new gtk:uri-launcher object.

Since 4.10
See also:
#2023-10-19
Function gtk:uri-launcher-launch (launcher parent cancellable func)
Arguments:
launcher -- a gtk:uri-launcher object
parent -- a parent gtk:window widget
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
Launch an application to open the URI. This may present an app chooser dialog to the user.

The callback will be called when the operation is completed. It should call the gtk:uri-launcher-launch-finish function to obtain the result.

Since 4.10
See also:
#2023-10-19
Function gtk:uri-launcher-launch-finish (launcher result)
Arguments:
launcher -- a gtk:uri-launcher object
result -- a g:async-result object with the result
Returns:
True if an application was launched, or false on error
Details:
Finishes the the gtk:uri-launcher-launch function call and returns the result.

Since 4.10
See also:
#2024-11-21

GtkFontDialog

Class gtk:font-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
filter
The filter property of type gtk:filter (Read / Write)
Sets a filter to restrict what fonts are shown in the font chooser dialog.
font-map
The font-map property of type pango:font-map (Read / Write)
Sets a custom font map to select fonts from. A custom font map can be used to present application specific fonts instead of or in addition to the normal system fonts.
language
The language property of type pango:language (Read / Write)
The language for which the font features are selected.
modal
The modal property of type :boolean (Read / Write)
Whether the font chooser dialog is modal.
Default value: true
title
The title property of type :string (Read / Write)
The title that may be shown on the font chooser dialog that is presented by the gtk:font-dialog-choose-font function.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:font-dialog object collects the arguments that are needed to present a font chooser dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the gtk:font-dialog-choose-font function or its variants. This API follows the GIO async pattern, and the result can be obtained by calling the corresponding finish function, such as the gtk:font-dialog-choose-font-finish function.

See the gtk:font-dialog-button widget for a convenient control that uses the gtk:font-dialog object and presents the results.

Since 4.10
See also:
#2024-5-2
Accessor gtk:font-dialog-filter (object)
Syntax:
(gtk:font-dialog-filter object) => filter
(setf (gtk:font-dialog-filter object) filter)
Arguments:
object -- a gtk:font-dialog object
filter -- a gtk:filter object
Details:
Accessor of the filter slot of the gtk:font-dialog class. The gtk:font-dialog-filter function returns the filter that decides which fonts to display in the font chooser dialog. The (setf gtk:font-dialog-filter) function adds a filter.

The gtk:filter object must be able to handle both pango:font-family and pango:font-face objects.

Since 4.10
See also:
#2024-5-2
Accessor gtk:font-dialog-font-map (object)
Syntax:
(gtk:font-dialog-font-map object) => fontmap
(setf (gtk:font-dialog-font-map object) fontmap)
Arguments:
object -- a gtk:font-dialog object
fontmap -- a pango:font-map object
Details:
Accessor of the font-map slot of the gtk:font-dialog class. The gtk:font-dialog-font-map function returns the fontmap from which fonts are selected, or nil for the default fontmap. The (setf gtk:font-dialog-font-map) function sets the fontmap from which fonts are selected. If fontmap is nil, the default fontmap is used.

Since 4.10
See also:
#2024-5-2
Accessor gtk:font-dialog-language (object)
Syntax:
(gtk:font-dialog-language object) => language
(setf (gtk:font-dialog-language object) language)
Arguments:
object -- a gtk:font-dialog object
fontmap -- a pango:language object
Details:
Accessor of the language slot of the gtk:font-dialog class. The gtk:font-dialog-language function returns the language for which font features are applied. The (setf gtk:font-dialog-language) function sets the language.

Since 4.10
See also:
#2024-5-2
Accessor gtk:font-dialog-modal (object)
Syntax:
(gtk:font-dialog-modal object) => modal
(setf (gtk:font-dialog-modal object) modal)
Arguments:
object -- a gtk:font-dialog object
modal -- a boolean whether the font chooser dialog is modal
Details:
Accessor of the modal slot of the gtk:font-dialog class. The gtk:font-dialog-modal function returns whether the font chooser dialog blocks interaction with the parent window while it is presented. The (setf gtk:font-dialog-modal) function sets whether the font chooser dialog blocks interaction with the parent window while it is presented.

Since 4.10
See also:
#2024-5-2
Accessor gtk:font-dialog-title (object)
Syntax:
(gtk:font-dialog-title object) => title
(setf (gtk:font-dialog-title object) title)
Arguments:
object -- a gtk:font-dialog object
title -- a string with the title
Details:
Accessor of the title slot of the gtk:font-dialog class. The gtk:font-dialog-title function returns the title that will be shown on the font chooser dialog. The (setf gtk:font-dialog-title) function sets the title.

Since 4.10
See also:
#2024-5-2
Function gtk:font-dialog-new ()
Returns:
The new gtk:font-dialog object.
Details:
Creates a new gtk:font-dialog object.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-choose-face (dialog parent face cancellable func)
Arguments:
dialog -- a gtk:font-dialog object
parent -- a parent gtk:window widget
face -- a pango:font-face object
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function initiates a font selection operation by presenting a dialog to the user for selecting a font face, that is a font family and style, but not a specific font size. The callback will be called when the dialog is dismissed. It should call the gtk:font-dialog-choose-face-finish function to obtain the result.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-choose-face-finish (dialog result)
Arguments:
dialog -- a gtk:font-dialog object
result -- a g:async-result object
Details:
Finishes the the gtk:font-dialog-choose-face function call and returns the resulting font face.

Since 4.10
See also:
#2024-11-21
Function gtk:font-dialog-choose-family (dialog parent family cancellable func)
Arguments:
dialog -- a gtk:font-dialog object
parent -- a parent gtk:window widget
family -- a pango:font-family object
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function initiates a font selection operation by presenting a dialog to the user for selecting a font family. The callback will be called when the dialog is dismissed. It should call the gtk:font-dialog-choose-family-finish function to obtain the result.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-choose-family-finish (dialog result)
Arguments:
dialog -- a gtk:font-dialog object
result -- a g:async-result object
Details:
Finishes the the gtk:font-dialog-choose-family function call and returns the resulting font family. This function never returns an error. If the operation is not finished successfully, the value passed as family to the gtk:font-dialog-choose-family function is returned.

Since 4.10
See also:
#2024-11-21
Function gtk:font-dialog-choose-font (dialog parent desc cancellable func)
Arguments:
dialog -- a gtk:font-dialog object
parent -- a parent gtk:window widget
desc -- a pango:font-description object
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function initiates a font selection operation by presenting a dialog to the user for selecting a font. The callback will be called when the dialog is dismissed. It should call the gtk:font-dialog-choose-font-finish function to obtain the result.

If you want to let the user select font features as well, use the gtk:font-dialog-choose-font-and-features function instead.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-choose-font-finish (dialog result)
Arguments:
dialog -- a gtk:font-dialog object
result -- a g:async-result object
Returns:
The pango:font-description object with the selected font.
Details:
Finishes the the gtk:font-dialog-choose-font function call and returns the resulting font description.

Since 4.10
See also:
#2024-11-21
Function gtk:font-dialog-choose-font-and-features (dialog parent desc cancellable func)
Arguments:
dialog -- a gtk:font-dialog object
parent -- a parent gtk:window widget
desc -- a pango:font-description object
cancellable -- a g:cancellable object to cancel the operation
func -- a g:async-ready-callback callback function to call when the operation is complete
Details:
This function initiates a font selection operation by presenting a dialog to the user for selecting a font and font features. Font features affect how the font is rendered, for example enabling glyph variants or ligatures.

The callback will be called when the dialog is dismissed. It should call the gtk:font-dialog-choose-font-and-features-finish function to obtain the result.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-choose-font-and-features-finish (dialog result)
Arguments:
dialog -- a gtk:font-dialog object
result -- a g:async-result object
Returns:
desc -- a pango:font-description object
features -- a string with the font features
language -- a pango:language object
Details:
Finishes the the gtk:font-dialog-choose-font function call and returns the resulting font description.

Since 4.10
See also:
#2024-11-21

GtkFontDialogButton

GEnum gtk:font-level
Declaration:
(gobject:define-genum "GtkFontLevel" font-level
  (:export t
   :type-initializer "gtk_font_level_get_type")
  (:family 0)
  (:face 1)
  (:font 2)
  (:features 3))  
Values:
:family
Select a font family.
:face
Select a font face, that is a family and a style.
:font
Select a font, that is, a face with a size, and possibly font variations).
:features
Select a font and font features.
Details:
The level of granularity for the font selection. Depending on this value, the pango:font-description instance that is returned by the gtk:font-dialog-button-font-desc function will have more or less fields set.

Since 4.10
See also:
2024-7-30
Class gtk:font-dialog-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
dialog
The dialog property of type gtk:font-dialog (Read / Write)
The font dialog that contains parameters for the font chooser dialog.
font-desc
The font-desc property of type pango:font-description (Read / Write)
The selected font. This property can be set to give the button its initial font, and it will be updated to reflect the users choice in the font chooser dialog. Listen to "notify::font-desc" signal to get informed about changes to the buttons font.
font-features
The font-features property of type :string (Read / Write)
The selected font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to the "notify::font-features" signal to get informed about changes to the buttons font features.
language
The language property of type pango:language (Read / Write)
The selected language for font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to "notify::language" to get informed about changes to the buttons language.
level
The level property of type gtk:font-level (Read / Write)
The level of detail for the font chooser dialog.
Default value: :font
use-font
The use-font property of type :boolean (Read / Write)
Whether the buttons label will be drawn in the selected font.
Default value: false
use-size
The use-size property of type :boolean (Read / Write)
Whether the buttons label will use the selected font size.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:font-dialog-button class is wrapped around a gtk:font-dialog object and allows to open a font chooser dialog to change the font.

Figure: GtkFontButton

It is the suitable widget for selecting a font in a preference dialog.

Since 4.10
CSS nodes:
fontbutton
╰── button.font
    ╰── [content]    
The gtk:font-dialog-button widget has a single CSS node with name fontbutton which contains a button node with the .font style class.
Signal Details:
The "activate" signal
lambda (fontbutton)    :run-first      
fontbutton
The gtk:font-dialog-button widget which received the signal.
Emitted when the font dialog button is activated. The signal is an action signal and emitting it causes the button to pop up its dialog. The signal can be directly emitted on objects from user code. Since 4.14
#2023-10-19
Accessor gtk:font-dialog-button-dialog (object)
Syntax:
(gtk:font-dialog-button-dialog object) => dialog
(setf (gtk:font-dialog-button-dialog object) dialog)
Arguments:
object -- a gtk:font-dialog-button object
dialog -- a gtk:font-dialog object
Details:
Accessor of the dialog slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-dialog function returns the font dialog. The (setf gtk:font-dialog-button-dialog) function sets a font dialog to use for creating the font chooser dialog that is presented when the user clicks the button.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-font-desc (object)
Syntax:
(gtk:font-dialog-button-font-desc object) => desc
(setf (gtk:font-dialog-button-font-desc object) desc)
Arguments:
object -- a gtk:font-dialog-button object
desc -- a pango:font-description instance
Details:
Accessor of the font-desc slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-font-desc function returns the font dialog. The (setf gtk:font-dialog-button-font-desc) function sets a font dialog to use for creating the font chooser dialog that is presented when the user clicks the button.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-font-features (object)
Syntax:
(gtk:font-dialog-button-font-features object) => features
(setf (gtk:font-dialog-button-font-features object) features)
Arguments:
object -- a gtk:font-dialog-button object
features -- a string with the selected font features
Details:
Accessor of the font-features slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-font-features function returns the font features of the button. The (setf gtk:font-dialog-button-font-features) function sets the font features.

This function is what should be used to obtain the font features that were chosen by the user. To get informed about changes, listen to the "notify::font-features" signal.

Note that the button will only let users choose font features if the level property is set to :features.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-language (object)
Syntax:
(gtk:font-dialog-button-language object) => language
(setf (gtk:font-dialog-button-language object) language)
Arguments:
object -- a gtk:font-dialog-button object
language -- a pango:language instance
Details:
Accessor of the language slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-language function returns the language that is used for font features. The (setf gtk:font-dialog-button-language) function sets the language.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-level (object)
Syntax:
(gtk:font-dialog-button-level object) => level
(setf (gtk:font-dialog-button-level object) level)
Arguments:
object -- a gtk:font-dialog-button object
level -- a gtk:font-level value
Details:
Accessor of the level slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-level function returns the level of detail at which this dialog lets the user select fonts. The (setf gtk:font-dialog-button-level) function sets the level.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-use-font (object)
Syntax:
(gtk:font-dialog-button-use-font object) => setting
(setf (gtk:font-dialog-button-use-font object) setting)
Arguments:
object -- a gtk:font-dialog-button object
setting -- a boolean whether the buttons label will be drawn in the selected font
Details:
Accessor of the use-font slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-use-font function returns whether the selected font is used in the label. The (setf gtk:font-dialog-button-use-font) function sets the property.

Since 4.10
See also:
#2023-10-19
Accessor gtk:font-dialog-button-use-size (object)
Syntax:
(gtk:font-dialog-button-use-size object) => setting
(setf (gtk:font-dialog-button-use-size object) setting)
Arguments:
object -- a gtk:font-dialog-button object
setting -- a boolean whether the buttons label will use the selected font size
Details:
Accessor of the use-size slot of the gtk:font-dialog-button class. The gtk:font-dialog-button-use-size function returns whether the selected font size is used in the label. The (setf gtk:font-dialog-button-use-size) function sets the property.

Since 4.10
See also:
#2023-10-19
Function gtk:font-dialog-button-new (&optional dialog)
Arguments:
dialog -- an optional gtk:font-dialog object to use
Details:
Creates a new gtk:font-dialog-button widget with the given gtk:font-dialog object. You can pass nil to this function and set a gtk:font-dialog object later. The button will be insensitive until that happens.

Since 4.10
See also:
#2023-10-19

GtkEmojiChooser

Class gtk:emoji-chooser
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:emoji-chooser widget is used by text widgets such as the gtk:entry or gtk:text-view widgets to offer users a convenient way to insert Emoji characters.

Figure: GtkEmojiChooser

The gtk:emoji-chooser widget emits the "emoji-picked" signal when an Emoji is selected.
CSS nodes:
popover
├── box.emoji-searchbar
│   ╰── entry.search
╰── box.emoji-toolbar
    ├── button.image-button.emoji-section
    ├── ...
    ╰── button.image-button.emoji-section    
Every gtk:emoji-chooser widget consists of a main node called popover. The contents of the popover are largely implementation defined and supposed to inherit general styles. The top searchbar used to search emoji and gets the .emoji-searchbar style class itself. The bottom toolbar used to switch between different emoji categories consists of buttons with the .emoji-section style class and gets the .emoji-toolbar style class itself.
Action Details:
The "scroll.section" action
Scrolls to the next or previous section.
direction
1 to scroll forward, -1 to scroll back
Signal Details:
The "emoji-picked" signal
lambda (chooser text)    :run-last      
chooser
The gtk:emoji-chooser widget.
text
The string with the Unicode sequence for the picked Emoji, in UTF-8.
The signal is emitted when the user selects an Emoji.
See also:
2023-8-28
Function gtk:emoji-chooser-new ()
Returns:
The new gtk:emoji-chooser widget.
Details:
Creates a new Emoji chooser dialog.
See also:
2023-8-28

Widgets for custom drawing

GtkDrawingArea

Class gtk:drawing-area
Superclasses:
Documented Subclasses:
None
Direct Slots:
content-height
The content-height property of type :int (Read / Write)
The content height.
Allowed values: >= 0
Default value: 0
content-width
The content-width property of type :int (Read / Write)
The content width.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:drawing-area widget is a widget that allows drawing with Cairo. It is essentially a blank widget. You can draw on it.

Figure: GtkDrawingArea

After creating a drawing area, the application may want to connect to:
  • The "GtkWidget::realize" signal to take any necessary actions when the widget is instantiated on a particular display. Create GDK resources in response to this signal.
  • The "GtkDrawingArea::resize" signal to take any necessary actions when the widget changes size.
  • Call the gtk:drawing-area-set-draw-func function to handle redrawing the contents of the widget.
The draw function is normally called when a drawing area first comes onscreen, or when it is covered by another window and then uncovered. You can also force a redraw by adding to the "damage region" of the drawing area’s window using the gtk:widget-queue-draw function. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented in the Cairo documentation. GDK offers additional API to integrate with Cairo, like the gdk:cairo-set-source-rgba or gdk:cairo-set-source-pixbuf functions.

To receive mouse events on a drawing area, you will need to use event controllers. To receive keyboard events, you will need to set the can-focus property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused.

If you need more complex control over your widget, you should consider creating your own GtkWidget subclass.
Examples:
The following example demonstrates using a drawing area to display a circle in the normal widget foreground color.
(defun do-drawing-area (&optional application)
  (let* ((area (make-instance 'gtk:drawing-area))
         (window (make-instance 'gtk:window
                                :application application
                                :child area
                                :title "Drawing Area"
                                :default-width 400
                                :default-height 300)))
    ;; Set a drawing function
    (gtk:drawing-area-set-draw-func area
        (lambda (widget cr width height)
          (let ((color (gtk:widget-color widget)))
            (gdk:cairo-set-source-rgba cr color)
            ;; Draw and fill a circle on the drawing area
            (cairo:arc cr
                       (/ width 2.0)
                       (/ height 2.0)
                       (- (/ (min width height) 2.0) 12)
                       0.0
                       (* 2.0 pi))
            (cairo:fill cr))))
    ;; Show the window
    (setf (gtk:widget-visible window) t)))    
Signal Details:
The "resize" signal
lambda (area width height)    :run-last      
area
The gtk:drawing-area widget that emitted the signal.
width
An integer with the width of the viewport.
height
An integer with the height of the viewport.
The signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, like for instance a backing surface.
2024-10-26
Accessor gtk:drawing-area-content-height (object)
Syntax:
(gtk:drawing-area-content-height object) => height
(setf (gtk:drawing-area-content-height object) height)
Arguments:
object -- a gtk:drawing-area widget
height -- an integer with the content height
Details:
Accessor of the content-height slot of the gtk:drawing-area class. The gtk:drawing-area-content-height function retrieves the content height of the drawing area. The (setf gtk:drawing-area-content-height) function sets the desired height of the contents.

Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw function is larger than the height set here. You can use the gtk:widget-valign function to avoid that.

If the height is set to 0, the default, the drawing area may disappear.
See also:
2024-10-26
Accessor gtk:drawing-area-content-width (object)
Syntax:
(gtk:drawing-area-content-width object) => width
(setf (gtk:drawing-area-content-width object) width)
Arguments:
object -- a gtk:drawing-area widget
width -- an integer with the content height
Details:
Accessor of the content-width slot of the gtk:drawing-area class. The gtk:drawing-area-content-width function retrieves the content width of the drawing area. The (setf gtk:drawing-area-content-width) function sets the desired width of the contents.

Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw function is larger than the height set here. You can use the gtk:widget-halign function to avoid that.

If the height is set to 0, the default, the drawing area may disappear.
See also:
2024-10-26
Function gtk:drawing-area-new ()
Returns:
The new gtk:drawing-area widget.
Details:
Creates a new drawing area.
See also:
2024-10-26
Callback gtk:drawing-area-draw-func
Syntax:
lambda (area cr width height)
Arguments:
area -- a gtk:drawing-area widget
cr -- a cairo:context-t instance to draw to
height -- an integer with the actual width of the contents
width -- an integer with the actual height of the contents
Details:
Whenever the drawing area needs to redraw, this callback function will be called. This function should exclusively redraw the contents of the drawing area and must not call any widget functions that cause changes.
See also:
2024-10-26
Function gtk:drawing-area-set-draw-func (area func)
Arguments:
area -- a gtk:drawing-area widget
func -- a gtk:drawing-area-draw-func callback function
Details:
Setting a draw function is the main thing you want to do when using a drawing area. The draw function is called whenever GTK needs to draw the contents of the drawing area to the screen.

The draw function will be called during the drawing stage of GTK. In the drawing stage it is not allowed to change properties of any GTK widgets or call any functions that would cause any properties to be changed. You should restrict yourself exclusively to drawing your contents in the draw function.

If what you are drawing does change, call the gtk:widget-queue-draw function on the drawing area. This will cause a redraw and will call the draw function again.
See also:
2024-10-26

GtkGlArea

Class gtk:gl-area
Superclasses:
Documented Subclasses:
None
Direct Slots:
allowed-apis
The allowed-apis property of type gdk:gl-api (Read / Write)
The allowed APIs. Since 4.12
Default value: '(:gl :gles)
api
The api property of type gdk:gl-api (Read)
The API currently in use. Since 4.12
Default value: '()
auto-render
The auto-render property of type :boolean (Read / Write)
If set to true the "render" signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If set to false the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering the gtk:gl-area-queue-render function must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.
Default value: true
context
The context property of type gdk:gl-context (Read)
The gdk:gl-context object used by the gtk:gl-area widget. The gtk:gl-area widget is responsible for creating the gdk:gl-context instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers.
has-depth-buffer
The has-depth-buffer property of type :boolean (Read / Write)
If set to true the widget will allocate and enable a depth buffer for the target framebuffer.
Default value: false
has-stencil-buffer
The has-stencil-buffer property of type :boolean (Read / Write)
If set to true the widget will allocate and enable a stencil buffer for the target framebuffer.
Default value: false
use-es
The use-es property of type :boolean (Read / Write)
If set to true the widget will try to create a gdk:gl-context instance using OpenGL ES instead of OpenGL. Deprecated since 4.12
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:gl-area widget is a widget that allows drawing with OpenGL.

Figure: GtkGLArea

The gtk:gl-area widget sets up its own gdk:gl-context object for the window it creates, and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering.

In order to draw, you have to connect to the "render" signal, or subclass the gtk:gl-area widget and override the render() virtual function.

The gtk:gl-area widget ensures that the gdk:gl-context object is associated with the drawing area of the widget, and it is kept updated when the size and position of the drawing area changes.

Drawing with GtkGLArea
The simplest way to draw using OpenGL commands in a gtk:gl-area widget is to create a widget instance and connect to the "render" signal.

The render() function will be called when the gtk:gl-area widget is ready for you to draw its content:
static gboolean
render (GtkGLArea *area, GdkGLContext *context)
{
  // inside this function it's safe to use GL; the given
  // GdkGLContext has been made current to the drawable
  // surface used by the `GtkGLArea` and the viewport has
  // already been set to be the size of the allocation

// we can start by clearing the buffer glClearColor (0, 0, 0, 0); glClear (GL_COLOR_BUFFER_BIT);

// draw your object // draw_an_object ();

// we completed our drawing; the draw commands will be // flushed at the end of the signal emission chain, and // the buffers will be drawn on the window return TRUE; }

void setup_glarea (void) { // create a GtkGLArea instance GtkWidget *gl_area = gtk_gl_area_new ();

// connect to the "render" signal g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL); }
If you need to initialize OpenGL state, for example buffer objects or shaders, you should use the "realize" signal. You can use the "unrealize" signal to clean up. Since the gdk:gl-context object creation and initialization may fail, you will need to check for errors, using the gtk:gl-area-error function. An example of how to safely initialize the GL state is:
static void
on_realize (GtkGLarea *area)
{
  // We need to make the context current if we want to
  // call GL API
  gtk_gl_area_make_current (area);

// If there were errors during the initialization or // when trying to make the context current, this // function will return a GError for you to catch if (gtk_gl_area_get_error (area) != NULL) return;

// You can also use gtk_gl_area_set_error() in order // to show eventual initialization errors on the // GtkGLArea widget itself GError *internal_error = NULL; init_buffer_objects (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; }

init_shaders (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } }
If you need to change the options for creating the gdk:gl-context object you should use the "create-context" signal.
Signal Details:
The "create-context" signal
lambda (area)    :run-last      
area
The gtk:gl-area widget that emitted the signal.
Returns
The newly created gdk:gl-context object. The gtk:gl-area widget will take ownership of the returned value.
The signal is emitted when the widget is being realized, and allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options. If context creation fails then the signal handler can use the gtk:gl-area-error function to register a more detailed error of how the construction failed.
The "render" signal
lambda (area context)    :run-last      
area
The gtk:gl-area widget that emitted the signal.
context
The gdk:gl-context object used by area.
Returns
True to stop other handlers from being invoked for the event. False to propagate the event further.
The signal is emitted every time the contents of the gtk:gl-area widget should be redrawn. The context is bound to the area prior to emitting this function, and the buffers are painted to the window once the emission terminates.
The "resize" signal
lambda (area width height)    :run-last      
area
The gtk:gl-area widget that emitted the signal.
width
The integer with the width of the viewport.
height
The integer with the height of the viewport.
The signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio. The GL context for the area is guaranteed to be current when this signal is emitted. The default handler sets up the GL viewport.
2024-10-26
Accessor gtk:gl-area-allowed-apis (object)
Syntax:
(gtk:gl-area-allowed-apis object) => apis
(setf (gtk:gl-area-allowed-apis object) apis)
Arguments:
object -- a gtk:gl-area widget
apis -- a gdk:gl-api value
Details:
Accessor of the allowed-apis slot of the gtk:gl-area class. The gtk:gl-area-allowed-apis function gets the allowed APIs. The (setf gtk:gl-area-allowed-apis) function sets the allowed APIs to create a context with. You should check the api property before drawing with either API. By default, all APIs are allowed.

Since 4.12
See also:
2024-10-26
Accessor gtk:gl-area-api (object)
Syntax:
(gtk:gl-area-api object) => api
Arguments:
object -- a gtk:gl-area widget
api -- a gdk:gl-api value
Details:
Accessor of the api slot of the gtk:gl-area class. The gtk:gl-area-api function gets the API is currently in use. If the GL area has not been realized yet, '() is returned.

Since 4.12
See also:
2024-10-26
Accessor gtk:gl-area-auto-render (object)
Syntax:
(gtk:gl-area-auto-render object) => setting
(setf (gtk:gl-area-auto-render object) setting)
Arguments:
object -- a gtk:gl-area widget
setting -- a boolean whether the area is auto rendering
Details:
Accessor of the auto-render slot of the gtk:gl-area class. The gtk:gl-area-auto-render function returns whether the area is in auto render mode or not. The (setf gtk:gl-area-auto-render) function sets the property.

If setting is true the "render" signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If setting is false the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering the gtk:gl-area-queue-render function must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.
See also:
2024-10-26
Accessor gtk:gl-area-context (object)
Syntax:
(gtk:gl-area-context object) => context
(setf (gtk:gl-area-context object) context)
Arguments:
object -- a gtk:gl-area widget
context -- a gdk:gl-context object
Details:
Accessor of the context slot of the gtk:gl-area class. The gtk:gl-area-context function retrieves the gdk:gl-context instance used by object.
See also:
2024-10-26
Accessor gtk:gl-area-has-depth-buffer (object)
Syntax:
(gtk:gl-area-has-depth-buffer object) => setting
(setf (gtk:gl-area-has-depth-buffer object) setting)
Arguments:
object -- a gtk:gl-area widget
setting -- a boolean whether the widget will allocate and enable a depth buffer
Details:
Accessor of the has-depth-buffer slot of the gtk:gl-area class. The gtk:gl-area-has-depth-buffer function returns whether the area has a depth buffer. The (setf gtk:gl-area-has-depth-buffer) function sets the property.

If setting is true the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none.
See also:
2024-10-26
Accessor gtk:gl-area-has-stencil-buffer (object)
Syntax:
(gtk:gl-area-has-stencil-buffer object) => setting
(setf (gtk:gl-area-has-stencil-buffer object) setting)
Arguments:
object -- a gtk:gl-area widget
setting -- a boolean whether the widget will allocate and enable a stencil buffer
Details:
Accessor of the has-stencil-buffer slot of the gtk:gl-area class. The gtk:gl-area-has-stencil-buffer function returns whether the area has a stencil buffer. The (setf gtk:gl-area-has-stencil-buffer) function sets the property.

If setting is true the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none.
See also:
2024-10-26
Accessor gtk:gl-area-use-es (object)
Syntax:
(gtk:gl-area-use-es object) => setting
(setf (gtk:gl-area-use-es object) setting)
Arguments:
object -- a gtk:gl-area widget
setting -- a boolean whether the widget should create an OpenGL ES context
Details:
Accessor of the use-es slot of the gtk:gl-area class. The gtk:gl-area-use-es function retrieves the property. The (setf gtk:gl-area-use-es) function sets whether the area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the gdk:gl-context instance before drawing with either API.
Warning:
This function is deprecated since 4.12. Use the gtk:gl-area-api function.
See also:
2024-10-26
Function gtk:gl-area-new ()
Returns:
The new gtk:gl-area widget.
Details:
Creates a new gtk:gl-area widget.
See also:
#2024-10-26
Function gtk:gl-area-make-current (area)
Arguments:
area -- a gtk:gl-area object
Details:
Ensures that the gdk:gl-context object used by area is associated with the the gtk:gl-area object. This function is automatically called before emitting the "render" signal, and does not normally need to be called by application code.
See also:
#2023-10-21
Function gtk:gl-area-queue-render (area)
Arguments:
area -- a gtk:gl-area object
Details:
Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget, ensuring that the "render" signal is emitted during the draw. This is only needed when the gtk:gl-area-auto-render function has been called with a false value. The default behaviour is to emit the "render" signal on each draw.
See also:
#2024-10-26
Function gtk:gl-area-attach-buffers (area)
Arguments:
area -- a gtk:gl-area object
Details:
Ensures that the area framebuffer object is made the current draw and read target, and that all the required buffers for the area are created and bound to the framebuffer. This function is automatically called before emitting the "render" signal, and does not normally need to be called by application code.
See also:
#2024-10-26
Function gtk:gl-area-required-version (area)
Syntax:
(gtk:gl-area-required-version area) => major, minor
(setf (gtk:gl-area-required-version area) '(major minor))
Arguments:
area -- a gtk:gl-area object
major -- an integer with the required major version
minor -- an integer with the required minor version
Details:
The gtk:gl-area-required-version function retrieves the required version of OpenGL. The (setf gtk:gl-area-required-version) function sets the required version of OpenGL to be used when creating the context for the widget. This function must be called before the area has been realized.
See also:
#2024-10-26

Scrolling

GtkScrollable

GEnum gtk:scrollable-policy
Declaration:
(gobject:define-genum "GtkScrollablePolicy" scrollable-policy
  (:export t
   :type-initializer "gtk_scrollable_policy_get_type")
  (:minimum 0)
  (:natural 1))  
Values:
:minimum
Scrollable adjustments are based on the minimum size.
:natural
Scrollable adjustments are based on the natural size.
Details:
Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation.
See also:
2023-8-6
Interface gtk:scrollable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
hadjustment
The hadjustment property of type gtk:adjustment (Read / Write / Construct)
The horizontal adjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent.
hscroll-policy
The hscroll-policy property of type gtk:scrollable-policy (Read / Write)
Determines whether horizontal scrolling should start once the scrollable widget is allocated less than its minimum width or less than its natural width.
Default value: :minimum
vadjustment
The vadjustment property of type gtk:adjustment (Read / Write / Construct)
The vertical adjustment of the scrollable widget. This adjustment is shared between the scrollable widget and its parent.
vscroll-policy
The vscroll-policy property of type gtk:scrollable-policy (Read / Write)
Determines whether vertical scrolling should start once the scrollable widget is allocated less than its minimum height or less than its natural height.
Default value: :minimum
Slot Access Functions:
Details:
The gtk:scrollable interface is an interface that is implemented by widgets with native scrolling ability. To implement this interface you should override the hadjustment and vadjustment properties.

Creating a scrollable widget
All scrollable widgets should do the following:
  • When a parent widget sets the adjustments of the scrollable child widget the widget should populate the lower, upper, step-increment, page-increment and page-size properties of the adjustment and connect to the "value-changed" signal.
  • Because its preferred size is the size for a fully expanded widget, the scrollable widget must be able to cope with underallocations. This means that it must accept any value passed to its GtkWidgetClass.size_allocate() function.
  • When the parent allocates space to the scrollable child widget, the widget should update the properties of the adjustments with new values.
  • When any of the adjustments emits the "value-changed" signal, the scrollable widget should scroll its contents.
See also:
2023-8-6
Accessor gtk:scrollable-hadjustment (object)
Syntax:
(gtk:scrollable-hadjustment object) => hadjustment
(setf (gtk:scrollable-hadjustment object) hadjustment)
Arguments:
object -- a gtk:scrollable widget
hadjustment -- a gtk:adjustment object
Details:
Accessor of the hadjustment slot of the gtk:scrollable interface. The gtk:scrollable-hadjustment function retrieves the adjustment used for horizontal scrolling. The (setf gtk:scrollable-hadjustment) function sets the horizontal adjustment.
See also:
2023-8-6
Accessor gtk:scrollable-hscroll-policy (object)
Syntax:
(gtk:scrollable-hscroll-policy object) => policy
(setf (gtk:scrollable-hscroll-policy object) policy)
Arguments:
object -- a gtk:scrollable widget
policy -- a gtk:scrollable-policy value for the horizontal scrolling policy
Details:
Accessor of the hscroll-policy slot of the gtk:scrollable interface. The gtk:scrollable-hscroll-policy function gets the horizontal scrolling policy which determines whether horizontal scrolling should start below the minimum width or below the natural width. The (setf gtk:scrollable-hscroll-policy) function sets the horizontal scrolling policy.
See also:
2023-8-6
Accessor gtk:scrollable-vadjustment (object)
Syntax:
(gtk:scrollable-vadjustment object) => vadjustment
(setf (gtk:scrollable-vadjustment object) vadjustment)
Arguments:
object -- a gtk:scrollable widget
vadjustment -- a gtk:adjustment object
Details:
Accessor of the vadjustment slot of the gtk:scrollable interface. The gtk:scrollable-vadjustment function retrieves the adjustment used for vertical scrolling. The (setf gtk:scrollable-vadjustment) function sets the vertical adjustment.
See also:
2023-8-6
Accessor gtk:scrollable-vscroll-policy (object)
Syntax:
(gtk:scrollable-vscroll-policy object) => policy
(setf (gtk:scrollable-vscroll-policy object) policy)
Arguments:
object -- a gtk:scrollable widget
policy -- a gtk:scrollable-policy value for the vertical scrolling policy
Details:
Accessor of the vscroll-policy slot of the gtk:scrollable interface. The gtk:scrollable-vscroll-policy function gets the vertical scrolling policy which determines whether vertical scrolling should start below the minimum height or below the natural height. The (setf gtk:scrollable-hscroll-policy) function sets the vertical scrolling policy.
See also:
2023-8-6
Function gtk:scrollable-border (scrollable)
Arguments:
scrollable -- a gtk:scrollable widget
Returns:
The gtk:border instance or nil.
Details:
Returns the size of a non-scrolling border around the outside of the scrollable widget. An example for this would be tree view headers. GTK can use this information to display overlayed graphics, like the overshoot indication, at the right position.
See also:
2023-8-6

GtkScrollbar

Class gtk:scrollbar
Superclasses:
Documented Subclasses:
None
Direct Slots:
adjustment
The adjustment property of type gtk:adjustment (Read / Write / Construct)
The adjustment that contains the current value of this scrollbar.
Returned by:
Slot Access Functions:
Details:
The gtk:scrollbar widget is a horizontal or vertical scrollbar, depending on the value of the orientation property.

Figure: GtkScrollbar

Its position and movement are controlled by the adjustment that is passed to or created by the gtk:scrollbar-new function. See the gtk:adjustment documentation for more details. The value property sets the position of the thumb and must be between the lower and upper - page-size values. The page-size property represents the size of the visible scrollable area. The step-increment and page-increment properties are added to or subtracted from the value property when the user asks to move by a step, using, for example, the cursor arrow keys, or by a page, using, for example, the Page Down/Page Up keys.
CSS nodes:
scrollbar
╰── range[.fine-tune]
    ╰── trough
        ╰── slider    
The gtk:scrollbar implementation has a main CSS node with name scrollbar and a subnode for its contents. The main node gets the .horizontal or .vertical style classes applied, depending on the orientation of the scrollbar. The range node gets the .fine-tune style class added when the scrollbar is in 'fine-tuning' mode.

Other style classes that may be added to scrollbars inside the gtk:scrolled-window widget include the .left, .right, .top, .bottom positional classes and .overlay-indicator, .dragging, .hovering style classes related to overlay scrolling.
Accessibility:
The gtk:scrollbar implementation uses the :scrollbar role of the gtk:accessible-role enumeration.
See also:
2024-6-1
Accessor gtk:scrollbar-adjustment (object)
Syntax:
(gtk:scrollbar-adjustment object) => adjustment
(setf (gtk:scrollbar-adjustment object) adjustment)
Arguments:
object -- a gtk:scrollbar widget
adjustment -- a gtk:adjustment object
Details:
Accessor of the adjustment slot of the gtk:scrollbar class. The gtk:scrollbar-adjustment function returns the adjustment of the scrollbar. The (setf gtk:scrollbar-adjustment) function makes the scrollbar use the given adjustment.
See also:
2023-8-6
Function gtk:scrollbar-new (orientation &optional adjustment)
Arguments:
orientation -- a gtk:orientation value for the orientation of the scrollbar
adjustment -- an optional gtk:adjustment object to use, the default is to create a new adjustment
Returns:
The new gtk:scrollbar widget.
Details:
Creates a new scrollbar with the given orientation.
See also:
2023-8-6

GtkScrolledWindow

GEnum gtk:policy-type
Declaration:
(gobject:define-genum "GtkPolicyType" policy-type
  (:export t
   :type-initializer "gtk_policy_type_get_type")
  (:always 0)
  (:automatic 1)
  (:never 2)
  (:external 3))  
Values:
:always
The scrollbar is always visible. The view size is independent of the content.
:automatic
The scrollbar will appear and disappear as necessary. For example, when all of a gtk:tree-view widget cannot be seen.
:never
The scrollbar should never appear. In this mode the content determines the size.
:external
Do not show a scrollbar, but do not force the size to follow the content. This can be used, for example, to make multiple scrolled windows share a scrollbar.
Details:
Determines how the size should be computed to achieve one of the visibility mode for the scrollbars.
See also:
2024-7-5
GEnum gtk:corner-type
Declaration:
(gobject:define-genum "GtkCornerType" corner-type
  (:export t
   :type-initializer "gtk_corner_type_get_type")
  (:top-left 0)
  (:bottom-left 1)
  (:top-right 2)
  (:bottom-right 3))  
Values:
:top-left
Place the scrollbars on the right and bottom of the widget (default behaviour).
:bottom-left
Place the scrollbars on the top and right of the widget.
:top-right
Place the scrollbars on the left and bottom of the widget.
:bottom-right
Place the scrollbars on the top and left of the widget.
Details:
Specifies which corner a child widget should be placed in when packed into a gtk:scrolled-window widget. This is effectively the opposite of where the scroll bars are placed.
See also:
2024-7-5
Class gtk:scrolled-window
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
hadjustment
The hadjustment property of type gtk:adjustment (Read / Write / Construct)
The adjustment for the horizontal position.
has-frame
The has-frame property of type :boolean (Read / Write)
Whether to draw a frame around the contents.
Default value: false
hscrollbar-policy
The hscrollbar-policy property of type gtk:policy-type (Read / Write)
When the horizontal scrollbar is displayed.
Default value: :automatic
kinetic-scrolling
The kinetic-scrolling property of type :boolean (Read / Write)
Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to input devices of :touchscreen type.
Default value: true
max-content-height
The max-content-height property of type :int (Read / Write)
The maximum content height of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1
max-content-width
The max-content-width property of type :int (Read / Write)
The maximum content width of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1
min-content-height
The min-content-height property of type :int (Read / Write)
The minimum content height of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1
min-content-width
The min-content-width property of type :int (Read / Write)
The minimum content width of the scrolled window, or -1 if not set.
Allowed values: >= -1
Default value: -1
overlay-scrolling
The overlay-scrolling property of type :boolean (Read / Write)
Whether overlay scrolling is enabled or not. If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlayed on top of the content, as narrow indicators.
Default value: true
propagate-natural-height
The propagate-natural-height property of type :boolean (Read / Write)
Whether the natural height of the child should be calculated and propagated through the requested natural height of the scrolled window. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child.
Default value: false
propagate-natural-width
The propagate-natural-width property of type :boolean (Read / Write)
Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child.
Default value: false
vadjustment
The vadjustment property of type gtk:adjustment (Read / Write / Construct)
The adjustment for the vertical position.
vscrollbar-policy
The vscrollbar-policy property of type gtk:policy-type (Read / Write)
When the vertical scrollbar is displayed.
Default value: :automatic
window-placement
The window-placement property of type gtk:corner-type (Read / Write)
Where the contents are located with respect to the scrollbars.
Default value: :top-left
Returned by:
Slot Access Functions:
Details:
The gtk:scrolled-window widget is a container that accepts a single child widget, makes that child scrollable using either internally added scrollbars or externally associated adjustments, and optionally draws a frame around the child.

Figure: GtkScrolledWindow

Widgets with native scrolling support, that is, those whose classes implement the gtk:scrollable interface, are added directly. For other types of widgets, the gtk:viewport class acts as an adaptor, giving scrollability to other widgets. The gtk:scrolled-window-child function intelligently accounts for whether or not the added child is a gtk:scrollable widget. If it is not, then it wraps the child in a gtk:viewport widget. Therefore, you can just add any child widget and not worry about the details.

If the gtk:scrolled-window-child function has added a gtk:viewport widget for you, you can remove both your added child widget from the gtk:viewport widget, and the gtk:viewport widget from the gtk:scrolled-window widget, like this:
(let ((window (make-instance 'gtk:scrolled-window))
      (child (make-instance 'gtk:button)))

;; GtkButton is not a GtkScrollable, so GtkScrolledWindow will ;; automatically add a GtkViewport. (setf (gtk:scrolled-window window) child)

;; Either of these will result in child being unparented: (setf (gtk:scrolled-window-child window) nil) ;; or (setf (gtk:viewport-child (gtk:scrolled-window-child window)) nil) ... )
Unless the hscrollbar-policy and vscrollbar-policy properties are :never or :external, the gtk:scrolled-window widget adds internal gtk:scrollbar widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the hadjustment and vadjustment properties that are associated with the gtk:scrolled-window widget. See the docs on the gtk:scrollbar widget for the details, but note that the step-increment and page-increment properties are only effective if the policy causes scrollbars to be present.

If a gtk:scrolled-window widget does not behave quite as you would like, or does not have exactly the right layout, it is very possible to set up your own scrolling with the gtk:scrollbar widget and for example a gtk:grid widget.

Touch support
The gtk:scrolled-window widget has built-in support for touch devices. When a touchscreen is used, swiping will move the scrolled window, and will expose 'kinetic' behavior. This can be turned off with the kinetic-scrolling property if it is undesired.

The gtk:scrolled-window widget also displays visual 'overshoot' indication when the content is pulled beyond the end, and this situation can be captured with the "edge-overshot" signal.

If no mouse device is present, the scrollbars will overlayed as narrow, auto-hiding indicators over the content. If traditional scrollbars are desired although no mouse is present, this behaviour can be turned off with the overlay-scrolling property.
CSS nodes:
The gtk:scrolled-window implementation has a main CSS node with name scrolledwindow. It uses subnodes with names overshoot and undershoot to draw the overflow and underflow indications. These nodes get the .left, .right, .top or .bottom style class added depending on where the indication is drawn.

The gtk:scrolled-window implementation also sets the .left, .right, .top, .bottom positional style classes and .overlay-indicator, .dragging, .hovering style classes related to overlay scrolling on its scrollbars.

If both scrollbars are visible, the area where they meet is drawn with a subnode named junction.
Signal Details:
The "edge-overshot" signal
lambda (window pos)    :run-last      
window
The gtk:scrolled-window widget which received the signal.
pos
The edge side as a value of the gtk:position-type enumeration that was hit.
The signal is emitted whenever user initiated scrolling makes the scrolled window firmly surpass, for example, with some edge resistance, the lower or upper limits defined by the adjustment in that orientation. A similar behavior without edge resistance is provided by the "edge-reached" signal. Note: The pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges.
The "edge-reached" signal
lambda (window pos)    :run-last      
window
The gtk:scrolled-window widget which received the signal.
pos
The edge side as a value of the gtk:position-type enumeration that was hit.
The signal is emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation. A similar behavior with edge resistance is provided by the "edge-overshot" signal. Note: The pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges.
The "move-focus-out" signal
lambda (window direction)    :action      
window
The gtk:scrolled-window widget which received the signal.
direction
Either the :tab-forward or :tab-backward value of the gtk:direction-type enumeration.
The signal is a keybinding signal which gets emitted when focus is moved away from the scrolled window by a keybinding. The "move-focus" signal is emitted with the direction value on this scrolled windows toplevel parent in the container hierarchy. The default bindings for this signal are the Tab+Ctrl and Tab+Ctrl+Shift keys.
The "scroll-child" signal
lambda (window scroll horizontal)    :action        
window
The gtk:scrolled-window widget which received the signal.
scroll
The value of the gtk:scroll-type enumeration describing how much to scroll.
horizontal
The boolean whether the keybinding scrolls the child horizontally or not.
Returns
The boolean whether the scroll happened.
The signal is a keybinding signal which gets emitted when a keybinding that scrolls is pressed. The horizontal or vertical adjustment is updated which triggers a signal that the scrolled windows child may listen to and scroll itself.
See also:
2024-7-5
Accessor gtk:scrolled-window-child (object)
Syntax:
(gtk:scrolled-window-child object) => child
(setf (gtk:scrolled-window-child object) child)
Arguments:
object -- a gtk:scrolled-window widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:scrolled-window class. The gtk:scrolled-window-child function gets the child widget of the scrolled window. The (setf gtk:scrolled-window-child) sets the child widget.
See also:
2024-7-5
Accessor gtk:scrolled-window-hadjustment (object)
Syntax:
(gtk:scrolled-window-hadjustment object) => adjustment
(setf (gtk:scrolled-window-hadjustment object) adjustment)
Arguments:
object -- a gtk:scrolled-window widget
adjustment -- a gtk:adjustment object with the horizontal scroll adjustment
Details:
Accessor of the hadjustment slot of the gtk:scrolled-window class. The gtk:scrolled-window-hadjustment function returns the horizontal adjustment of the scrollbar, used to connect the horizontal scrollbar to the horizontal scroll functionality of the child widget. The (setf gtk:scrolled-window-hadjustment) function sets the adjustment for the horizontal scrollbar.
See also:
2024-7-5
Accessor gtk:scrolled-window-has-frame (object)
Syntax:
(gtk:scrolled-window-has-frame object) => setting
(setf (gtk:scrolled-window-child object) setting)
Arguments:
object -- a gtk:scrolled-window widget
setting -- a boolean whether to draw a frame around the contents
Details:
Accessor of the has-frame slot of the gtk:scrolled-window class. The gtk:scrolled-window-has-frame function gets whether the scrolled window draws a frame. The (setf gtk:scrolled-window-has-frame) function changes the frame drawn around the contents of the scrolled window.
See also:
2024-7-5
Accessor gtk:scrolled-window-hscrollbar-policy (object)
Syntax:
(gtk:scrolled-window-hscrollbar-policy object) => policy
(setf (gtk:scrolled-window-hscrollbar-policy object) policy)
Arguments:
object -- a gtk:scrolled-window widget
policy -- a gtk:policy-type value
Details:
Accessor of the hscrollbar-policy slot of the gtk:scrolled-window class.
See also:
2024-7-5
Accessor gtk:scrolled-window-kinetic-scrolling (object)
Syntax:
(gtk:scrolled-window-kinetic-scrolling object) => scrolling
(setf (gtk:scrolled-window-kinetic-scrolling object) scrolling)
Arguments:
object -- a gtk:scrolled-window widget
scrolling -- true to enable kinetic scrolling
Details:
Accessor of the kinetic-scrolling slot of the gtk:scrolled-window class. The gtk:scrolled-window-kinetic-scrolling function returns the specified kinetic scrolling behavior. The (setf gtk:scrolled-window-kinetic-scrolling) function turns kinetic scrolling on or off.

Kinetic scrolling only applies to input devices of :touchscreen type.
See also:
2024-7-5
Accessor gtk:scrolled-window-max-content-height (object)
Syntax:
(gtk:scrolled-window-max-content-height object) => height
(setf (gtk:scrolled-window-max-content-height object) height)
Arguments:
object -- a gtk:scrolled-window widget
height -- an integer with the maximum content height
Details:
Accessor of the max-content-height slot of the gtk:scrolled-window class. The gtk:scrolled-window-max-content-height function returns the maximum content height that the scrolled window should keep visible. The scrolled window will grow up to this height before it starts scrolling the content. The (setf gtk:scrolled-window-max-content-height) function sets the maximum height.

It is a programming error to set the maximum content height to a value smaller than the min-content-height value.
See also:
2024-7-5
Accessor gtk:scrolled-window-max-content-width (object)
Syntax:
(gtk:scrolled-window-max-content-width object) => width
(setf (gtk:scrolled-window-max-content-width object) width)
Arguments:
object -- a gtk:scrolled-window widget
width -- an integer with the maximum content width
Details:
Accessor of the max-content-width slot of the gtk:scrolled-window class. The gtk:scrolled-window-max-content-width function returns the maximum content width that the scrolled window should keep visible. The scrolled window will grow up to this width before it starts scrolling the content. The (setf gtk:scrolled-window-max-content-width) function sets the maximum width.

It is a programming error to set the maximum content width to a value smaller than the min-content-width value.
See also:
2024-7-5
Accessor gtk:scrolled-window-min-content-height (object)
Syntax:
(gtk:scrolled-window-min-content-height object) => height
(setf (gtk:scrolled-window-min-content-height object) height)
Arguments:
object -- a gtk:scrolled-window widget
height -- an integer with the minimal content height
Details:
Accessor of the min-content-height slot of the gtk:scrolled-window class. The gtk:scrolled-window-min-content-height function gets the minimal content height of the scrolled window that the scrolled window should keep visible. Note that this can and, usually will, be smaller than the minimum size of the content. The (setf gtk:scrolled-window-min-content-heigth) function sets the minimum height.
See also:
2024-7-5
Accessor gtk:scrolled-window-min-content-width (object)
Syntax:
(gtk:scrolled-window-min-content-width object) => width
(setf (gtk:scrolled-window-min-content-width object) width)
Arguments:
object -- a gtk:scrolled-window widget
width -- an integer with the minimal content width
Details:
Accessor of the min-content-width slot of the gtk:scrolled-window class. The gtk:scrolled-window-min-content-width function gets the minimum content width of the scrolled window that the scrolled window should keep visible. Note that this can and, usually will, be smaller than the minimum size of the content. The (setf gtk:scrolled-window-min-content-width) function sets the minimum width.
See also:
2024-7-5
Accessor gtk:scrolled-window-overlay-scrolling (object)
Syntax:
(gtk:scrolled-window-overlay-scrolling object) => scrolling
(setf (gtk:scrolled-window-overlay-scrolling object) scrolling)
Arguments:
object -- a gtk:scrolled-window widget
scrolling -- a boolean whether to enable overly scrolling
Details:
Accessor of the overlay-scrolling slot of the gtk:scrolled-window class. The gtk:scrolled-window-overlay-scrolling function returns whether overlay scrolling is enabled for this scrolled window. The (setf gtk:scrolled-window-overlay-scrolling) function enables or disables overlay scrolling.
See also:
2024-7-5
Accessor gtk:scrolled-window-propagate-natural-height (object)
Syntax:
(gtk:scrolled-window-propagate-natural-height object) => propagate
(setf (gtk:scrolled-window-propagate-natural-height object) propagate)
Arguments:
object -- a gtk:scrolled-window widget
propagate -- a boolean whether to propagate natural height
Details:
Accessor of the propagate-natural-height slot of the gtk:scrolled-window class. The gtk:scrolled-window-propagate-natural-height function reports whether the natural height of the child will be calculated and propagated through the requested natural height of the scrolled window. The (setf gtk:scrolled-window-propagate-natural-height) function sets the property.
See also:
2024-7-5
Accessor gtk:scrolled-window-propagate-natural-width (object)
Syntax:
(gtk:scrolled-window-propagate-natural-width object) => propagate
(setf (gtk:scrolled-window-propagate-natural-width object) propagate)
Arguments:
object -- a gtk:scrolled-window widget
propagate -- a boolean whether to propagate natural width
Details:
Accessor of the propagate-natural-width slot of the gtk:scrolled-window class. The gtk:scrolled-window-propagate-natural-width function reports whether the natural width of the child will be calculated and propagated through the requested natural width of the scrolled window. The (setf gtk:scrolled-window-propagate-natural-width) function sets the property.
See also:
2024-7-5
Accessor gtk:scrolled-window-vadjustment (object)
Syntax:
(gtk:scrolled-window-vadjustment object) => adjustment
(setf (gtk:scrolled-window-vadjustment object) adjustment)
Arguments:
object -- a gtk:scrolled-window widget
adjustment -- a gtk:adjustment object with the vertical scroll adjustment
Details:
Accessor of the vadjustment slot of the gtk:scrolled-window class. The gtk:scrolled-window-vadjustment function returns the vertical adjustment of the scrollbar, used to connect the vertical scrollbar to the vertical scroll functionality of the child widget. The (setf gtk:scrolled-window-vadjustment) function sets the adjusment for the vertical scrollbar.
See also:
2024-7-5
Accessor gtk:scrolled-window-vscrollbar-policy (object)
Syntax:
(gtk:scrolled-window-vscrollbar-policy object) => policy
(setf (gtk:scrolled-window-vscrollbar-policy object) policy)
Arguments:
object -- a gtk:scrolled-window widget
policy -- a value of the gtk:policy-type enumeration
Details:
Accessor of the vscrollbar-policy slot of the gtk:scrolled-window class.
See also:
2024-7-5
Accessor gtk:scrolled-window-window-placement (object)
Syntax:
(gtk:scrolled-window-window-placement object) => placement
(setf (gtk:scrolled-window-window-placement object) placement)
Arguments:
object -- a gtk:scrolled-window widget
placement -- a value of the gtk:corner-type enumeration
Details:
Accessor of the window-placement slot of the gtk:scrolled-window class. Where the contents are located with respect to the scrollbars.
See also:
2024-7-5
Function gtk:scrolled-window-new (&optional hadjustment vadjustment)
Arguments:
hadjustment -- a gtk:adjustment object with the horizontal adjustment
vadjustment -- a gtk:adjustment object with the vertical adjustment
Returns:
The new gtk:scrolled-window widget.
Details:
Creates a new scrolled window. The two optional arguments are the adjustments of the scrolled window. These will be shared with the scrollbars and the child widget to keep the bars in sync with the child. Usually you want to use the default values for the adjustments, which will cause the scrolled window to create them for you.
See also:
2024-7-5
Function gtk:scrolled-window-hscrollbar (window)
Arguments:
window -- a gtk:scrolled-window widget
Returns:
The horizontal gtk:scrollbar widget of the scrolled window, or nil if it does not have one.
Details:
Returns the horizontal scrollbar of the scrolled window.
See also:
2024-7-5
Function gtk:scrolled-window-vscrollbar (window)
Arguments:
window -- a gtk:scrolled-window widget
Returns:
The vertical gtk:scrollbar widget of the scrolled window, or nil if it does not have one.
Details:
Returns the vertical scrollbar of the scrolled window.
See also:
2024-7-5
Function gtk:scrolled-window-policy (window)
Syntax:
(gtk:scrolled-window-policy window) => hpolicy, vpolicy
(setf (gtk:scrolled-window-policy window) (list hpolicy vpolicy))
Arguments:
window -- a gtk:scrolled-window widget
hpolicy -- a value of the gtk:policy-type enumeration for the policy for horizontal bar
vpolicy -- a value of the gtk:policy-type enumeration for the policy for vertical bar
Details:
Accessor of the policy values of the srolled window. The gtk:scrolled-window-policy function retrieves the current policy values for the horizontal and vertical scrollbars. The (setf gtk:scrolled-window-policy) function sets the scrollbar policy.

The policy determines when the scrollbar should appear. It is a value from the gtk:policy-type enumeration. If :always, the scrollbar is always present. If :never, the scrollbar is never present. If :automatic, the scrollbar is present only if needed, that is, if the slider part of the bar would be smaller than the trough - the display is larger than the page size.
See also:
2024-7-5
Function gtk:scrolled-window-placement (window)
Syntax:
(gtk:scrolled-window-placement window) => placement
(setf (gtk:scrolled-window-placement window) placement)
Arguments:
window -- a gtk:scrolled-window widget
placement -- a value of the gtk:corner-type enumeration with the position of the child window
Details:
The gtk:scrolled-window-placement function gets the placement of the contents with respect to the scrollbars for the scrolled window. The (setf gtk:scrolled-window-placement) function sets the placement of the contents.

The default is :top-left, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in the gtk:corner-type enumeration are :top-right, :bottom-left, and :bottom-right.

See also the gtk:scrolled-window-unset-placement function.
Notes:
In contrast to the gtk:scrolled-window-window-placement function the gtk:scrolled-window-placement function updates the scrolled window after setting the new value for the window placement.
See also:
2024-7-5
Function gtk:scrolled-window-unset-placement (window)
Arguments:
window -- a gtk:scrolled-window widget
Details:
Unsets the placement of the contents with respect to the scrollbars for the scrolled window. If no window placement is set for a scrolled window, it defaults to the :top-left value of the gtk:corner-type enumeration.

See also the gtk:scrolled-window-placement function.
See also:
2024-7-5

GtkViewport

Class gtk:viewport
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget of the viewport.
scroll-to-focus
The scroll-to-focus property of type :boolean (Read / Write)
Whether to scroll when the focus changes.
Default value: true
Slot Access Functions:
Details:
The gtk:viewport widget acts as an adaptor class, implementing scrollability for child widgets that lack their own scrolling capabilities. Use the gtk:viewport widget to scroll child widgets such as the widgets gtk:grid, gtk:box, and so on.

The gtk:viewport widget will start scrolling content only if allocated less than the minimum size of the child widget in a given orientation.
CSS nodes:
The gtk:viewport widget has a single CSS node with name viewport.
Accessibility:
The gtk:viewport implementation uses the :group role of the gtk:accessible-role enumeration.
See also:
2024-7-5
Accessor gtk:viewport-child (object)
Syntax:
(gtk:viewport-child object) => child
(setf (gtk:viewport-child object) child)
Arguments:
object -- a gtk:viewport widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:viewport class.
See also:
2024-7-5
Accessor gtk:viewport-scroll-to-focus (object)
Syntax:
(gtk:viewport-scroll-to-focus object) => setting
(setf (gtk:viewport-scroll-to-focus object) setting)
Arguments:
object -- a gtk:viewport widget
setting -- a boolean whether to keep the focus widget scrolled to view
Details:
Accessor of the scroll-to-focus slot of the gtk:viewport class. The gtk:viewport-scroll-to-focus function gets whether the viewport is scrolling to keep the focused child in view. The (setf gtk:viewport-scroll-to-focus) function sets whether the viewport should automatically scroll to keep the focused child in view.
See also:
2024-7-5
Function gtk:viewport-new (&optional hadjustment vadjustment)
Arguments:
hadjustment -- an optional horizontal gtk:adjustment object
vadjustment -- an optional vertical gtk:adjustment object
Returns:
The new gtk:viewport widget.
Details:
Creates a new viewport with the given adjustments, or with default adjustments if none are given.
See also:
2024-7-5
Function gtk:viewport-scroll-to (viewport descendant &optional scroll)
Arguments:
viewport -- a gtk:viewport widget
descendant -- a descendant gtk:widget object of the viewport
scroll -- an optional gtk:scroll-info instance, or the default nil value to scroll into view
Details:
Scrolls a descendant of the viewport into view. The viewport and the descendant widget must be visible and mapped for this function to work, otherwise no scrolling will be performed.

Since 4.12
See also:
2025-4-7

Keyboard shortcuts

Utilities for accelerators

We have various utility functions to parse and generate textual representations of keyboard accelerators. If you want to set up keyboard accelerators for widgets, the gtk:shortcut-trigger object is probably more convenient than the functions in this section.
Function gtk:accelerator-valid (keyval mask)
Arguments:
keyval -- an unsigned integer with a GDK keyval
mask -- a gdk:modifier-type value
Returns:
True if the accelerator is valid.
Details:
Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the GDK_KEY_a keyval plus GDK_CONTROL_MASK is valid - this is a Ctrl+a accelerator. But, you cannot, for instance, use the GDK_KEY_Control_L keyval as an accelerator.
See also:
2023-8-4
Function gtk:accelerator-parse (accelerator)
Arguments:
accelerator -- a string representing an accelerator
Returns:
key -- an unsigned integer with an accelerator keyval
mask -- a gdk:modifier-type accelerator modifier mask, or nil
Details:
Parses a string representing an accelerator. The format looks like <Control>a or <Shift><Alt>F1 or <Release>z. The last one is for key release.

The parser is fairly liberal and allows lower or upper case, and also abbreviations such as <Ctl> and <Ctrl>. Key names are parsed using the gdk:keyval-from-name function. For character keys the name is not the symbol, but the lowercase name, for example, one would use <Ctrl>minus instead of <Ctrl>-.

If the parse fails, the key argument will be set to 0.
Examples:
(gtk:accelerator-parse "<Control>a")
=> 97
=> (:CONTROL-MASK)
(gtk:accelerator-parse "<Shift><Alt>F1")
=> 65470
=> (:SHIFT-MASK :ALT-MASK)
(gtk:accelerator-parse "<Control>minus")
=> 45
=> (:CONTROL-MASK)
(gtk:accelerator-parse "not valid")
=> 0
=> NIL    
See also:
2023-8-4
Function gtk:accelerator-name (key mask)
Arguments:
key -- an unsigned integer with the accelerator keyval
mask -- a gdk:modifier-type value with the accelerator modifier mask
Returns:
The string with the accelerator name.
Details:
Converts an accelerator keyval and modifier mask into a string parseable by the gtk:accelerator-parse function. If you need to display accelerators in the user interface, see the gtk:accelerator-label function.
Examples:
(gtk:accelerator-name 65470 '(:shift-mask :alt-mask))
=> "<Shift><Alt>F1"    
See also:
2023-8-4
Function gtk:accelerator-label (key mask)
Arguments:
key -- an unsigned integer with the accelerator keyval
mask -- a gdk:modifier-type value with the accelerator modifier mask
Returns:
The string representing the accelerator.
Details:
Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user.
Examples:
(gtk:accelerator-label 65470 '(:shift-mask :mod1-mask))
=> "Shift+Alt+F1"    
See also:
2023-8-4
Function gtk:accelerator-default-mod-mask ()
Returns:
The gdk:modifier-type value with the accelerator modifier mask.
Details:
Gets the default modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for GDK_LOCK_MASK.
See also:
2023-8-4

GtkShortcutManager

Interface gtk:shortcut-manager
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:shortcut-manager interface is used to implement shortcut scopes. This is important for gtk:native widgets that have their own surface, since the event controllers that are used to implement managed and global scopes are limited to the same native.

Every widget that implements the gtk:shortcut-manager interface will be used with the :managed value of the gtk:shortcut-scope enumeration.

Examples for widgets implementing the gtk:shortcut-manager interface are the gtk:window and gtk:popover widgets.
See also:
2024-11-1
Function gtk:shortcut-manager-add-controller (manager controller)
Arguments:
manager -- a gtk:shortcut-manager object
controller -- a gtk:shortcut-controller object
Details:
Adds a gtk:shortcut-controller object to be managed.
See also:
#2024-11-1
Function gtk:shortcut-manager-remove-controller (manager controller)
Arguments:
manager -- a gtk:shortcut-manager object
controller -- a gtk:shortcut-controller object
Details:
Remove a gtk:shortcut-controller object that had previously been added.
See also:
#2024-11-1

GtkShortcut

Class gtk:shortcut
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
action
The action property of type gtk:shortcut-action (Read / Write)
The action that gets activated by the shortcut.
arguments
The arguments property of type g:variant (Read / Write)
Arguments passed to activation.
Default value: cffi:null-pointer
trigger
The trigger property of type gtk:shortcut-trigger (Read / Write)
The trigger that triggers the shortcut.
Returned by:
Slot Access Functions:
Details:
The gtk:shortcut object is the low level object used for managing keyboard shortcuts. It contains a description of how to trigger the shortcut via a gtk:shortcut-trigger object and a way to activate the shortcut on a widget via the gtk:shortcut-action object.

The actual work is usually done via the gtk:shortcut-controller object, which decides if and when to activate a shortcut. Using that controller directly however is rarely necessary as various higher level convenience APIs exist on gtk:widget objects that make it easier to use shortcuts in GTK.

The gtk:shortcut class does provide functionality to make it easy for users to work with shortcuts, either by providing informational strings for display purposes or by allowing shortcuts to be configured.
See also:
2024-11-1
Accessor gtk:shortcut-action (object)
Syntax:
(gtk:shortcut-action object) => action)
(setf (gtk:shortcut-action object) action)
Arguments:
object -- a gtk:shortcut object
action -- a gtk:shortcut-action object
Details:
Accessor of the action slot of the gtk:shortcut class. The gtk:shortcut-action function gets the action that is activated by the shortcut. The (setf gtk:shortcut-action) function sets the new action. If action is nil, the nothing action will be used.
See also:
2024-11-1
Accessor gtk:shortcut-arguments (object)
Syntax:
(gtk:shortcut-arguments object) => args)
(setf (gtk:shortcut-arguments object) args)
Arguments:
object -- a gtk:shortcut object
args -- a g:variant parameter to pass when activating the shortcut
Details:
Accessor of the arguments slot of the gtk:shortcut class. The gtk:shortcut-arguments function gets the arguments that are passed when activating the shortcut. The (setf gtk:shortcut-arguments) function sets the arguments.
See also:
2024-11-1
Accessor gtk:shortcut-trigger (object)
Syntax:
(gtk:shortcut-trigger object) => trigger)
(setf (gtk:shortcut-trigger object) trigger)
Arguments:
object -- a gtk:shortcut object
trigger -- a gtk:shortcut-trigger object
Details:
Accessor of the trigger slot of the gtk:shortcut class. The gtk:shortcut-trigger function gets the trigger used to trigger the shortcut. The (setf gtk:shortcut-trigger) function sets the new trigger. If trigger is nil, the never trigger will be used.
See also:
2024-11-1
Function gtk:shortcut-new (trigger action)
Arguments:
trigger -- a gtk:shortcut-trigger object that will trigger the shortcut
action -- a gtk:shortcut-action object that will be activated upon triggering
Returns:
The new gtk:shortcut object.
Details:
Creates a new shortcut that is triggered by trigger and then activates action.
See also:
2024-11-1

GtkShortcutTrigger

Class gtk:shortcut-trigger
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Returned by:
Details:
The gtk:shortcut-trigger object is the object used to track if a gtk:shortcut object should be activated. For this purpose, the gtk:shortcut-trigger-trigger function can be called on a gdk:event instance.

The gtk:shortcut-trigger implementation contains functions that allow easy presentation to end users as well as being printed for debugging.

All gtk:shortcut-trigger objects are immutable, you can only specify their properties during construction. If you want to change a trigger, you have to replace it with a new one.
See also:
2024-11-1
Function gtk:shortcut-trigger-parse-string (str)
Arguments:
str -- a string to parse
Returns:
The new gtk:shortcut-trigger object, or nil on error.
Details:
Tries to parse the given string into a trigger. On success, the parsed trigger is returned. When parsing failed, nil is returned. The accepted strings are: Note that you will have to escape the < and &gt; characters when specifying triggers in XML files, such as GtkBuilder UI files. Use &lt; instead of < and &gt; instead of &gt;.
See also:
2024-11-1
Function gtk:shortcut-trigger-trigger (shortcut event enable)
Arguments:
shortcut -- a gtk:shortcut-trigger object
event -- a gdk:event instance
enable -- a boolean whether mnemonics should trigger
Returns:
The gdk:key-match value whether the event triggered the shortcut.
Details:
Checks if the given event triggers shortcut. Usually the value of enable is determined by checking that the passed in event is a key event and has the right modifiers set.
See also:
#2024-11-1
Function gtk:shortcut-trigger-to-string (shortcut)
Arguments:
shortcut -- a gtk:shortcut-trigger object
Returns:
The human-readable string.
Details:
Prints the given trigger into a human-readable string.
See also:
2024-11-1
Function gtk:shortcut-trigger-to-label (shortcut display)
Arguments:
shortcut -- a gtk:shortcut-trigger object
display -- a gdk:display object
Returns:
The string with the textual representation for the given trigger.
Details:
Gets textual representation for the given trigger. This function is returning a translated string for presentation to end users for example in menu items or in help texts.

The display in use may influence the resulting string in various forms, such as resolving hardware keycodes or by causing display-specific modifier names. The form of the representation may change at any time and is not guaranteed to stay identical.
See also:
2024-11-1
Class gtk:keyval-trigger
Superclasses:
gtk:shortcut-trigger, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
keyval
The keyval property of type :uint (Read / Write / Construct only)
The key value for the trigger.
modifiers
The modifiers property of type gdk:modifier-type (Read / Write / Construct only)
The key modifiers for the trigger.
Returned by:
Slot Access Functions:
Details:
A gtk:shortcut-trigger object that triggers when a specific keyval and (optionally) modifiers are pressed.
See also:
2024-11-1
Accessor gtk:keyval-trigger-keyval (object)
Syntax:
(gtk:keyval-trigger-keyval object) => keyval
Arguments:
object -- a gtk:keyval-trigger object
keyval -- an unsigned integer with the keyval
Details:
Accessor of the keyval slot of the gtk:keyval-trigger class. The gtk:keyval-trigger-keyval function returns the keyval that must be pressed to succed triggering object.
See also:
2024-11-1
Accessor gtk:keyval-trigger-modifiers (object)
Syntax:
(gtk:keyval-trigger-modifiers object) => modifiers
Arguments:
object -- a gtk:keyval-trigger object
modifiers -- a gdk:modifier-type value
Details:
Accessor of the modifiers slot of the gtk:keyval-trigger class. The gtk:keyval-trigger-modifiers function returns the modifiers that must be present to succed triggering object.
See also:
2024-11-1
Function gtk:keyval-trigger-new (keyval modifiers)
Arguments:
keyval -- a char or an unsigned integer with the keyval to trigger for
modifiers -- a gdk:modifier-type value that need to be present
Returns:
The new gtk:shortcut-trigger object.
Details:
Creates a gtk:shortcut-trigger object that will trigger whenever the key with the given keyval and modifiers is pressed.
See also:
2024-11-1
Class gtk:mnemonic-trigger
Superclasses:
gtk:shortcut-trigger, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
keyval
The keyval property of type :uint (Read / Write / Construct only)
The key value for the trigger.
Returned by:
Slot Access Functions:
Details:
A gtk:shortcut-trigger object that triggers when a specific mnemonic is pressed.
See also:
2024-11-1
Accessor gtk:mnemonic-trigger-keyval (object)
Syntax:
(gtk:mnemonic-trigger-keyval object) => keyval
Arguments:
object -- a gtk:mnemonic-trigger object
keyval -- an unsigned integer with the keyval
Details:
Accessor of the keyval slot of the gtk:mnemonic-trigger class. The gtk:mnemonic-trigger-keyval function returns the keyval that must be pressed to succed triggering object.
See also:
2024-11-1
Function gtk:mnemonic-trigger-new (keyval)
Arguments:
keyval -- a char or an unsigned integer with the keyval to trigger for
Returns:
The new gtk:mnemonic-trigger object.
Details:
Creates a gtk:shortcut-trigger object that will trigger whenever the key with the given keyval is pressed and mnemonics have been activated. Mnemonics are activated by calling code when a key event with the right modifiers is detected.
See also:
2024-11-1
Class gtk:alternative-trigger
Superclasses:
gtk:shortcut-trigger, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
first
The first property of type gtk:shortcut-trigger (Read / Write / Construct only)
The first trigger to check.
second
The second property of type gtk:shortcut-trigger (Read / Write / Construct only)
The second trigger to check.
Returned by:
Slot Access Functions:
Details:
A gtk:shortcut-trigger object that triggers when either of two gtk:shortcut-trigger objects trigger.
See also:
2024-11-1
Accessor gtk:alternative-trigger-first (object)
Syntax:
(gtk:alternative-trigger-first object) => shortcut)
Arguments:
object -- a gtk:mnemonic-trigger object
shortcut -- a first gtk:shortcut-trigger object
Details:
Accessor of the first slot of the gtk:alternative-trigger class. The gtk:alternative-trigger-first function gets the first of the two alternative triggers that may trigger shortcut. The gtk:alternative-trigger-second function will return the other one.
See also:
2024-11-1
Accessor gtk:alternative-trigger-second (object)
Syntax:
(gtk:alternative-trigger-second object) => shortcut)
Arguments:
object -- a gtk:mnemonic-trigger object
shortcut -- a second gtk:shortcut-trigger object
Details:
Accessor of the second slot of the gtk:alternative-trigger class. The gtk:alternative-trigger-second function gets the second of the two alternative triggers that may trigger shortcut. The gtk:alternative-trigger-first function will return the other one.
See also:
2024-11-1
Function gtk:alternative-trigger-new (first second)
Arguments:
first -- a gtk:shortcut-trigger object
second -- a gtk:shortcut-trigger object
Returns:
The new gtk:shortcut-trigger object.
Details:
Creates a gtk:shortcut-trigger object that will trigger whenever either of the two given triggers gets triggered. Note that nesting is allowed, so if you want more than two alternative, create a new alternative trigger for each option.
See also:
2024-11-1
Class gtk:never-trigger
Superclasses:
gtk:shortcut-trigger, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A gtk:shortcut-trigger object that never triggers.
See also:
2024-11-1
Function gtk:never-trigger-get ()
Returns:
The gtk:never-trigger object.
Details:
Gets the never trigger. This is a singleton for a trigger that never triggers. Use this trigger because it implements all virtual functions.
See also:
2024-11-1

GtkShortcutAction

GFlags gtk:shortcut-action-flags
Declaration:
(gobject:define-gflags "GtkShortcutActionFlags" shortcut-action-flags
  (:export t
   :type-initializer "gtk_shortcut_action_flags_get_type")
  (:exclusive #.(ash 1 0)))  
Values:
:exclusive
The action is the only action that can be activated. If this flag is not set, a future activation may select a different action.
Details:
List of flags that can be passed to action activation. More flags may be added in the future.
See also:
2024-11-1
Class gtk:shortcut-action
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Returned by:
Details:
The gtk:shortcut-action object is the object used to describe what a gtk:shortcut object should do when triggered. To activate a gtk:shortcut-action object manually, the gtk:shortcut-action-activate function can be called.

The gtk:shortcut-action implementation contain functions that allow easy presentation to end users as well as being printed for debugging.

All gtk:shortcut-action objects are immutable, you can only specify their properties during construction. If you want to change an action, you have to replace it with a new one. If you need to pass arguments to an action, these are specified by the higher-level gtk:shortcut object.

GTK provides various actions:
GtkMnemonicAction
A shortcut action that calls the gtk:widget-mnemonic-activate function.
GtkCallbackAction
A shortcut action that invokes a given callback.
GtkSignalAction
A shortcut action that emits a given signal.
GtkActivateAction
A shortcut action that calls the gtk:widget-activate function.
GtkNamedAction
A shortcut action that calls the gtk:widget-activate-action function.
GtkNothingAction
A shortcut action that does nothing.
See also:
2024-11-1
Function gtk:shortcut-action-parse-string (str)
Arguments:
str -- a string to parse
Returns:
The new gtk:shortcut-action object, or nil on error.
Details:
Tries to parse the given string into an action. On success, the parsed action is returned. When parsing failed, nil is returned. The accepted strings are:
nothing
for a gtk:nothing-action object
activate
for a gtk:activate-action object
mnemonic-activate
for a gtk:mnenomic-action object
action(name)
for a gtk:named-action object for the action named name
signal(name)
for a gtk:signal-action object for the signal name
See also:
2024-11-1
Function gtk:shortcut-action-to-string (action)
Arguments:
shortcut -- a gtk:shortcut-action object
Returns:
The human-readable string.
Details:
Prints the given action into a human-readable string.
See also:
2024-11-1
Function gtk:shortcut-action-activate (action flags widget args)
Arguments:
shortcut -- a gtk:shortcut-action object
flags -- a gtk:shortcut-action-flags value
widget -- a gtk:widget object
args -- an array of g:variant parameters to pass
Returns:
True if the action was activaed successfully.
Details:
Activates the action on the widget with the given args. Note that some actions ignore the passed in flags, widget or args.

Activation of an action can fail for various reasons. If the action is not supported by the widget, if the args do not match the action or if the activation otherwise had no effect, false will be returned.
See also:
#2024-11-1
Class gtk:nothing-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A gtk:shortcut-action object that does nothing.
See also:
2024-11-1
Function gtk:nothing-action-get ()
Returns:
The gtk:nothing-action object.
Details:
Gets the nothing action. This is an action that does nothing and where activating it always fails.
See also:
2024-11-1
Class gtk:callback-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A gtk:shortcut-action object that invokes a callback.
See also:
2024-11-1
Callback gtk:shortcut-func
Syntax:
lambda (widget args)
Arguments:
widget -- a gtk:widget object passed to the activation
args -- an array of g:variant parameters passed to the activation
Details:
Prototype for shortcuts based on user callbacks.
See also:
2024-11-1
Function gtk:callback-action-new (func)
Arguments:
func -- a gtk:shortcut-func callback function to call
Returns:
The new gtk:callback-action object.
Details:
Create a custom action that calls the given callback when activated.
See also:
2024-11-1
Class gtk:mnemonic-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
See also:
2024-11-1
Function gtk:mnemonic-action-get ()
Returns:
The gtk:shortcut-action mnemonic action.
Details:
Gets the mnemonic action. This is an action that calls the gtk:widget-mnemonic-activate function on the given widget upon activation.
See also:
2024-11-1
Class gtk:activate-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A gtk:shortcut-action that calls the gtk:widget-activate function.
See also:
2024-11-1
Function gtk:activate-action-get ()
Returns:
The gtk:shortcut-action activate action.
Details:
Gets the activate action. This is an action that calls the gtk:widget-activate function on the given widget upon activation.
See also:
2024-11-1
Class gtk:signal-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
signal-name
The signal-name property of type :string (Read / Write / Construct only)
The name of the signal to emit.
Returned by:
Slot Access Functions:
Details:
A gtk:shortcut-action that emits a signal. Signals that are used in this way are referred to as keybinding signals, and they are expected to be defined with the :action value of the g:signal-flags flags.
See also:
2024-11-1
Accessor gtk:signal-action-signal-name (object)
Syntax:
(gtk:signal-action-signal-name object) => name
(setf (gtk:signal-action-signal-name object) name)
Arguments:
object -- a gtk:signal-action object
name -- a string with the name of the signal to emit
Details:
Accessor of the signal-name slot of the gtk:signal-action class. The gtk:signal-action-signal-name function returns the name of the signal that will be emitted.
See also:
2024-11-1
Function gtk:signal-action-new (name)
Arguments:
name -- a string with the name of the signal to emit
Returns:
The gtk:signal-action object.
Details:
Creates an action that when activated, emits the given action signal on the provided widget unpacking the given args into arguments passed to the signal.
See also:
2024-11-1
Class gtk:named-action
Superclasses:
gtk:shortcut-action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
action-name
The action-name property of type :string (Read / Write / Construct only)
The name of the action to activate.
Returned by:
Slot Access Functions:
Details:
A gtk:shortcut-action that activates an action by name.
See also:
2024-11-1
Accessor gtk:named-action-action-name (object)
Syntax:
(gtk:named-action-action-name object) => name
(setf (gtk:named-action-action-name object) name)
Arguments:
object -- a gtk:named-action object
name -- a string with the name of the actopm that will be activated
Details:
Accessor of the action-name slot of the gtk:named-action class. The gtk:named-action-action-name function returns the name of the action that will be activated.
See also:
2024-11-1
Function gtk:named-action-new (name)
Arguments:
name -- a string with the detailed name of the action
Returns:
The new gtk:named-action object.
Details:
Creates an action that when activated, activates the action given by the detailed name on the widget passing the given arguments to it. See the gtk:widget-insert-action-group function for how to add actions to widgets.
See also:
2024-11-1

Interfaces

GtkActionable

Interface gtk:actionable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
action-name
The action-name property of type :string (Read / Write)
The name of the associated action, like "app.quit".
Default value: nil
action-target
The action-target property of type g:variant (Read / Write)
The parameter for action invocations.
Allowed values: a g:variant parameter
Default value: cffi:null-pointer
Slot Access Functions:
Details:
The gtk:actionable interface provides a convenient way of associating widgets with actions on a gtk:application-window widget or gtk:application instance. It primarily consists of two properties: action-name and action-target. There are also some convenience APIs for setting these properties.

The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the "win." or "app." prefix that are associated with the gtk:application-window widget or the gtk:application instance, but other action groups that are added with the gtk:widget-insert-action-group function will be consulted as well.
See also:
2025-2-23
Accessor gtk:actionable-action-name (object)
Syntax:
(gtk:actionable-action-name object) => name
(setf (gtk:actionable-action-name object) name)
Arguments:
object -- a gtk:actionable widget
name -- a string for the action name, or nil
Details:
Accessor of the action-name slot of the gtk:actionable inferface. The gtk:actionable-action-name function gets the action name for object, or nil if none is set. The (setf gtk:actionable-action-name) function specifies the name of the action with which this widget should be associated. If the name argument is nil then the widget will be unassociated from any previous action. Usually this function is used when the widget is located, or will be located, within the hierarchy of a gtk:application-window widget.

Names are of the form "win.save" or "app.quit" for actions on the containing gtk:application-window widget or its associated gtk:application instance, respectively. This is the same form used for actions in the g:menu object associated with the window.
Examples:
(let ((button (make-instance 'gtk:button)))
  (setf (gtk:actionable-action-name button) "win.save")
  (gtk:actionable-action-name button))
=> "win.save"    
See also:
2025-2-23
Accessor gtk:actionable-action-target (object)
Syntax:
(gtk:actionable-action-target object) => value
(setf (gtk:actionable-action-target object) value)
Arguments:
object -- a gtk:actionable widget
value -- a g:variant parameter as the target value, or cffi:null-pointer
Details:
Accessor of the action-target slot of the gtk:actionable inferface. The gtk:actionable-action-target function gets the current target value of an actionable widget. The (setf gtk:actionable-action-target) function sets the target value. If the value argument is a cffi:null-pointer then the target value is unset.

The target value has two purposes. First, it is used as the parameter to activation of the action associated with the gtk:actionable widget. Second, it is used to determine if the widget should be rendered as "active". The widget is active if the state is equal to the given target.

Consider the example of associating a set of buttons with a g:action object with string state in a typical radio button situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the state of the action to change to that value. Since the state of the action is now equal to the target value of the button, the button will now be rendered as active and the other buttons, with different targets, rendered inactive.
Examples:
(let ((button (make-instance 'gtk:button)))
  (setf (gtk:actionable-action-target button) (g:variant-new-int16 128))
  (g:variant-int16 (gtk:actionable-action-target button)))
=> 128    
Notes:
The C implementation has the additional gtk_actionable_get_action_target_value() and gtk_actionable_set_action_target_value() functions. In the Lisp implementation these functions are replaced by the gtk:actionable-action-target function.
See also:
2025-2-23
Function gtk:actionable-set-detailed-action-name (actionable name)
Arguments:
actionable -- a gtk:actionable widget
name -- a string for the detailed action name
Details:
Sets the action name and associated string target value of an actionable widget. This allows for the effect of both the gtk:actionable-action-name and gtk:actionable-action-target functions in the common case that the target is string-valued.

The name argument is a string of the form "action::target" where "action" is the action name and "target" is the string to use as the target.
Examples:
(setq button (make-instance 'gtk:button))
=> #<GTK-BUTTON {1004A8C973}>
(gtk:actionable-set-detailed-action-name button "win.justify::left")
(values (gtk:actionable-action-name button)
        (g:variant-string (gtk:actionable-action-target button)))
=> "win.justify"
=> "left"    
See also:
2025-2-23

GtkOrientable

Interface gtk:orientable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
orientation
The orientation property of type gtk:orientation (Read / Write)
The orientation of the orientable widget.
Default value: :horizontal
Slot Access Functions:
Details:
The gtk:orientable interface is implemented by all widgets that can be oriented horizontally or vertically. A gtk:orientable widget is more flexible in that it allows the orientation to be changed at runtime, allowing the widget to "flip".
CSS nodes:
The gtk:widget objects that implement the gtk:orientable interface will automatically acquire the horizontal or vertical CSS class, depending on the value of the orientation property.
See also:
2024-9-26
Accessor gtk:orientable-orientation (object)
Syntax:
(gtk:orientable-orientation object) => orientation
(setf (gtk:orientable-orientation object) orientation)
Arguments:
object -- a gtk:orientable widget
orientation -- a value of the gtk:orientation enumeration
Details:
Accessor of the orientation slot of the gtk:orientable interface. The gtk:orientable-orientation function returns the orientation of the orientable widget. The (setf gtk:orientable-orientation) function sets the orientation.
See also:
2024-9-26

Abstract Base Classes

GtkWidget

GBoxed gtk:requisition
Declaration:
(glib:define-gboxed-cstruct requisition "GtkRequisition"
  (:export t
   :type-initializer "gtk_requistion_get_type")
  (width :int :initform 0)
  (height :int :initform 0))  
Values:
width
The integer with the desired width of the widget.
height
The integer with the desired height of the widget.
Returned by:
Slot Access Functions:
Details:
The gtk:requisition structure represents the desired size of a widget. See the section called "Height-for-width Geometry Management" in the gtk:widget documentation for more information.
See also:
2025-2-13
Accessor gtk:requisition-width (instance)
Syntax:
(gtk:requisition-width instance) => width
(setf (gtk:requisition-width instance) width)
Arguments:
instance -- a gtk:requisition instance
width -- an integer for the width
Details:
Accessor of the width slot of the gtk:requisition structure.
Examples:
(defvar requisition (gtk:requisition-new)) => REQUISITION
(setf (gtk:requisition-width requisition) 100) => 100
(gtk:requisition-width requisition) => 100    
See also:
2025-2-13
Accessor gtk:requisition-height (instance)
Syntax:
(gtk:requisition-height instance) => height
(setf (gtk:requisition-height instance) height)
Arguments:
instance -- a gtk:requisition instance
height -- an integer for the height
Details:
Accessor of the height slot of the gtk:requisition structure.
Examples:
(defvar requisition (gtk:requisition-new)) => REQUISITION
(setf (gtk:requisition-height requisition) 100) => 100
(gtk:requisition-height requisition) => 100    
See also:
2025-2-13
Function gtk:requisition-new (&key width height)
Arguments:
width -- an integer for the width, default 0
height -- an integer for the height, default 0
Returns:
The new gtk:requisition instance.
Details:
Allocates a new gtk:requisition instance.
See also:
2025-2-13
Function gtk:requisition-copy (requisition)
Arguments:
requisition -- a gtk:requisition instance
Returns:
The gtk:requisition instance with the copy of requisition.
Details:
Copies a gtk:requisition instance.
See also:
2025-2-13
Class gtk:widget
Superclasses:
Documented Subclasses:
Direct Slots:
can-focus
The can-focus property of type :boolean (Read / Write)
Whether the widget can accept the input focus.
Default value: false
can-target
The can-target property of type :boolean (Read / Write)
Whether the widget can receive pointer events.
Default value: true
css-classes
The css-classes property of type g:strv-t (Read / Write)
The list of CSS classes applied to the widget.
css-name
The css-name property of type :string (Read / Write / Construct only)
The name of the widget in the CSS tree. This property is meant to be set by widget implementations, typically in their instance function.
cursor
The cursor property of type gdk:cursor (Read / Write)
The cursor used by the widget.
focus-on-click
The focus-on-click property of type :boolean (Read / Write)
Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus.
Default value: true
focusable
The focusable property of type :boolean (Read / Write)
Whether the widget itself will accept the input focus.
halign
The halign property of type gtk:align (Read / Write)
How to distribute horizontal space if the widget gets extra space.
Default value: :fill
has-default
The has-default property of type :boolean (Read)
Whether the widget is the default widget.
Default value: false
has-focus
The has-focus property of type :boolean (Read)
Whether the widget has the input focus.
Default value: false
has-tooltip
The has-tooltip property of type :boolean (Read / Write)
Enables or disables the emission of the "query-tooltip" signal on the widget. A true value indicates that the widget can have a tooltip, in this case the widget will be queried using the "query-tooltip" signal to determine whether it will provide a tooltip or not.
Default value: false
height-request
The height-request property of type :int (Read / Write)
Override for height request of the widget, or -1 if natural request should be used.
Allowed values: >= -1
Default value: -1
hexpand
The hexpand property of type :boolean (Read / Write)
Whether to expand horizontally.
Default value: false
hexpand-set
The hexpand-set property of type :boolean (Read / Write)
Whether to use the hexpand property.
Default value: false
layout-manager
The layout-manager property of type gtk:layout-manager (Read / Write)
The layout manager to use to compute the preferred size of the widget, and allocate its children. This property is meant to be set by widget implementations, typically in their instance init function.
margin-bottom
The margin-bottom property of type :int (Read / Write)
Margin on bottom side of the widget. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0
margin-end
The margin-end property of type :int (Read / Write)
Margin on end of the widget, horizontally. This property supports left-to-right text directions. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0
margin-start
The margin-start property of type :int (Read / Write)
Margin on start of the widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0
margin-top
The margin-top property of type :int (Read / Write)
Margin on top side of the widget. This property adds margin outside of the normal size request of the widget.
Allowed values: [0,32767]
Default value: 0
name
The name property of type :string (Read / Write)
The name of the widget.
Default value: nil
opacity
The opacity property of type :double (Read / Write)
The requested opacity of the widget.
Allowed values: [0.0,1.0]
Default value: 1.0
overflow
The overflow property of type gtk:overflow (Read / Write)
How content outside the content area of the widget is treated. This property is meant to be set by widget implementations, typically in their instance init function.
parent
The parent property of type gtk:widget (Read)
The parent widget of this widget.
receives-default
The receives-default property of type :boolean (Read / Write)
Whether the widget will receive the default action when it is focused.
Default value: false
root
The root property of type gtk:root (Read)
The root widget of the widget tree containing this widget. This will be nil if the widget is not contained in a root widget.
scale-factor
The scale-factor property of type :int (Read)
The scale factor of the widget.
Allowed values: >= 1
Default value: 1
sensitive
The sensitive property of type :boolean (Read / Write)
Whether the widget responds to input.
Default value: true
tooltip-markup
The tooltip-markup property of type :string (Read / Write)
Sets the text of the tooltip to be the given string, which is marked up with the Pango text markup language. This is a convenience property which will take care of getting the tooltip shown if the given string is not nil. The has-tooltip property will automatically be set to true and there will be taken care of the "query-tooltip" signal in the default signal handler. Note that if both the tooltip-text and tooltip-markup properties are set, the last one wins.
Default value: nil
tooltip-text
The tooltip-text property of type :string (Read / Write)
Sets the text of the tooltip to be the given string. This is a convenience property which will take care of getting the tooltip shown if the given string is not nil. The has-tooltip property will automatically be set to true and there will be taken care of the "query-tooltip" signal in the default signal handler. Note that if both the tooltip-text and tooltip-markup properties are set, the last one wins.
Default value: nil
valign
The valign property of type gtk:align (Read / Write)
How to distribute vertical space if the widget gets extra space.
Default value: :fill
vexpand
The vexpand property of type :boolean (Read / Write)
Whether to expand vertically.
Default value: false
vexpand-set
The vexpand-set property of type :boolean (Read / Write)
Whether to use the vexpand property.
Default value: false
visible
The visible property of type :boolean (Read / Write)
Whether the widget is visible.
Default value: false
width-request
The width-request property of type :int (Read / Write)
Override for width request of the widget, or -1 if natural request should be used.
Allowed values: >= -1
Default value: -1
Slot Access Functions:
Details:
The gtk:widget class is the base class all widgets in GTK derive from. It manages the widget life cycle, layout, states and style.

Height-for-width Geometry Management
GTK uses a height-for-width and width-for-height geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given and similar for width-for-height. The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height.

GTK also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment of :baseline, and is inside a container that supports baselines and has a natural "row" that it aligns to the baseline, or a baseline assigned to it by the grandparent.

If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was :fill, but the selected baseline can be found via the gtk:widget-allocated-baseline function. If this has a value other than -1 you need to align the widget such that the baseline appears at the position.

GtkWidget as GtkBuildable
The gtk:widget implementation of the gtk:buildable interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties.

If the widget uses a gtk:layout-manager object, the gtk:widget implementation supports a custom <layout> element, used to define layout properties:
<object class="GtkGrid" id="my_grid">
  <child>
    <object class="GtkLabel" id="label1">
      <property name="label">Description</property>
      <layout>
        <property name="column">0</property>
        <property name="row">0</property>
        <property name="row-span">1</property>
        <property name="column-span">1</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkEntry" id="description_entry">
      <layout>
        <property name="column">1</property>
        <property name="row">0</property>
        <property name="row-span">1</property>
        <property name="column-span">1</property>
      </layout>
    </object>
  </child>
</object>  
The gtk:widget implementation allows style information such as style classes to be associated with widgets, using the custom <style> element:
<object class="GtkButton" id="button1">
  <style>
    <class name="my-special-button-class"/>
    <class name="dark-button"/>
  </style>
</object>  
The gtk:widget implementation allows defining accessibility information, such as properties, relations, and states, using the custom <accessibility> element:
<object class="GtkButton" id="button1">
  <accessibility>
    <property name="label">Download</property>
    <relation name="labelled-by">label1</relation>
  </accessibility>
</object>  
Building composite widgets from template XML
The gtk:widget implementation exposes some facilities to automate the proceedure of creating composite widgets using templates.

To create composite widgets with gtk:builder XML, one must associate the interface description with the widget class at class initialization time using the gtk:widget-class-set-template function.

The interface description semantics expected in composite template descriptions is slightly different from regulare gtk:builder XML. Unlike regular interface descriptions, the gtk:widget-class-set-template function will expect a <template> tag as a direct child of the toplevel <interface> tag. The <template> tag must specify the "class" attribute which must be the type name of the widget. Optionally, the "parent" attribute may be specified to specify the direct parent type of the widget type, this is ignored by the gtk:builder object but can be used by UI design tools to introspect what kind of properties and internal children exist for a given type when the actual type does not exist.

The XML which is contained inside the <template> tag behaves as if it were added to the <object> tag defining the widget itself. You may set properties on the widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend the widget in the normal way you would with <object> tags.

Additionally, <object> tags can also be added before and after the initial <template> tag in the normal way, allowing one to define auxilary objects which might be referenced by other widgets declared as children of the <template> tag.

Example: A gtk:builder template definition
<interface>
  <template class="FooWidget" parent="GtkBox">
    <property name="orientation">GTK_ORIENTATION_HORIZONTAL</property>
    <property name="spacing">4</property>
    <child>
      <object class="GtkButton" id="hello_button">
        <property name="label">Hello World</property>
      </object>
    </child>
    <child>
      <object class="GtkButton" id="goodbye_button">
        <property name="label">Goodbye World</property>
      </object>
    </child>
  </template>
</interface>    
Signal Details:
The "destroy" signal
lambda (widget)    :no-hooks      
widget
The gtk:widget object which received the signal.
Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released.
The "direction-changed" signal
lambda (widget direction)    :run-first      
widget
The gtk:widget object on which the signal is emitted.
direction
The previous gtk:text-direction value with the text direction of the widget.
Emitted when the text direction of a widget changes.
The "hide" signal
lambda (widget)    :run-first      
widget
The gtk:widget object which received the signal.
Emitted when the widget is hidden, for example with the gtk:widget-hide function.
The "keynav-failed" signal
lambda (widget direction)    :run-last      
widget
The gtk:widget object which received the signal.
direction
The gtk:direction-type value with the direction of movement.
Returns
True if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).
Gets emitted if keyboard navigation fails.
The "map" signal
lambda (widget)    :run-first      
widget
The gtk:widget object which received the signal.
Emitted when the widget is going to be mapped, that is when the widget is visible, which is controlled with the gtk:widget-visible function, and all its parents up to the toplevel widget are also visible. Once the map has occurred, the "map-event" signal will be emitted. The "map" signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of the "unmap" signal.
The "mnemonic-activate" signal
lambda (widget cycling)    :run-last      
widget
The gtk:widget object which received the signal.
cycling
True if there are other widgets with the same mnemonic.
Returns
True to stop other handlers from being invoked for the event, false to propagate the event further.
The default handler for this signal activates the widget if the cycling argument is false, or just makes the widget grab focus if the cycling argument is true.
The "move-focus" signal
lambda (widget direction)    :action      
widget
The gtk:widget object which received the signal.
direction
The gtk:direction-type value with the direction.
The "query-tooltip" signal
lambda (widget x y mode tooltip)    :run-last      
widget
The gtk:widget object which received the signal.
x
The integer with the x coordinate of the cursor position where the request has been emitted, relative to the left side of the widget.
y
The integer with the y coordinate of the cursor position where the request has been emitted, relative to the top of the widget.
mode
True if the tooltip was trigged using the keyboard.
tooltip
The gtk:tooltip object.
Returns
True if the tooltip should be shown right now, false otherwise.
Emitted when the tooltip of the widget is about to be shown. This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering "above" the widget or emitted when the widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for the widget. If this is the case true should be returned, false otherwise. Note that if the mode argument is true, the x and y values are undefined and should not be used. The signal handler is free to manipulate the tooltip argument with the therefore destined function calls.
The "realize" signal
lambda (widget)    :run-first      
widget
The gtk:widget object which received the signal.
Emitted when the widget is associated with a gdk:surface object, which means that the gtk:widget-realize function has been called or the widget has been mapped, that is, it is going to be drawn.
The "show" signal
lambda (widget)      
widget
The gtk:widget object which received the signal.
Emitted when the widget is shown, for example with the gtk:widget-show function.
The "state-flags-changed" signal
lambda (widget flags)    :run-first      
widget
The gtk:widget object which received the signal.
flags
The previous gtk:state-flags value with the state flags.
Emitted when the widget state changes.
The "unmap" signal
lambda (widget)    :run-first      
widget
The gtk:widget object which received the signal.
Emitted when the widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. As the "unmap" signal indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.
The "unrealize" signal
lambda (widget)    :run-last      
widget
The gtk:widget object which received the signal.
Emitted when the gdk:surface object associated with the widget is destroyed, which means that the gtk:widget-unrealize function has been called or the widget has been unmapped, that is, it is going to be hidden.
See also:
2025-2-13
Accessor gtk:widget-can-focus (object)
Syntax:
(gtk:widget-can-focus object) => setting
(setf (gtk:widget-can-focus object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether or not widget can own the input focus
Details:
Accessor of the can-focus slot of the gtk:widget class. The gtk:widget-can-focus function returns true if the widget can own the input focus, false otherwise. The (setf gtk:widget-can-focus) function sets whether the widget can own the input focus.

See the gtk:widget-grab-focus function for actually setting the input focus on a widget.
See also:
2025-2-13
Accessor gtk:widget-can-target (object)
Syntax:
(gtk:widget-can-target object) => setting
(setf (gtk:widget-can-target object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether or not widget can receive pointer events
Details:
Accessor of the can-target slot of the gtk:widget class. The gtk:widget-can-target function returns whether the widget can be the target of pointer events. The (setf gtk:widget-can-target) function sets the property.
See also:
2025-2-13
Accessor gtk:widget-css-classes (object)
Syntax:
(gtk:widget-css-classes object) => classes
(setf (gtk:widget-css-classes object) classes)
Arguments:
object -- a gtk:widget object
classes -- a list of strings for the CSS classes applied to the widget
Details:
Accessor of the css-classes slot of the gtk:widget class. The gtk:widget-css-classes function returns the list of style classes applied to the widget. The (setf gtk:widget-css-classes) function clears all style classes applied to the widget and replace them with classes.
See also:
2025-2-13
Accessor gtk:widget-css-name (object)
Syntax:
(gtk:widget-css-name object) => name
(setf (gtk:widget-css-name object) name)
Arguments:
object -- a gtk:widget object
name -- a string for the name of the widget in the CSS tree
Details:
Accessor of the css-name slot of the gtk:widget class. The gtk:widget-css-name function returns the CSS name that is used for the widget. This property is meant to be set by widget implementations, typically in their instance init function.
See also:
2025-2-13
Accessor gtk:widget-cursor (object)
Syntax:
(gtk:widget-cursor object) => cursor
(setf (gtk:widget-cursor object) cursor)
Arguments:
object -- a gtk:widget object
cursor -- a gdk:cursor object
Details:
Accessor of the cursor slot of the gtk:widget class. The gtk:widget-cursor function queries the cursor set on the widget. The (setf gtk:widget-cursor) function sets the cursor to be shown when pointer devices point towards the widget. If the cursor property is nil, the widget will use the cursor inherited from the parent widget.
See also:
2025-2-13
Accessor gtk:widget-focus-on-click (object)
Syntax:
(gtk:widget-focus-on-click object) => setting
(setf (gtk:widget-focus-on-click object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the widget should grab focus
Details:
Accessor of the focus-on-click slot of the gtk:widget class. The gtk:widget-focus-on-click function returns true if the widget should grab focus when it is clicked with the mouse. The (setf gtk:widget-focus-on-click) function sets whether the widget should grab focus.

Making mouse clicks not grab focus is useful in places like toolbars where you do not want the keyboard focus removed from the main area of the application.
See also:
2025-2-13
Accessor gtk:widget-focusable (object)
Syntax:
(gtk:widget-focusable object) => setting
(setf (gtk:widget-focusable object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether object itself will accept the input focus
Details:
Accessor of the focusable slot of the gtk:widget class. The gtk:widget-focusable function determines whether the widget can own the input focus. The (setf gtk:widget-focusable) function specifies whether the widget can own the input focus.

Widget implementations should set the focusable property to true in their init function if they want to receive keyboard input. Note that having the focusable property be true is only one of the necessary conditions for being focusable. A widget must also have the sensitive and can-focus properties be true and not have an ancestor that has the can-focus property set to false in order to receive input focus. See the gtk:widget-grab-focus function for actually setting the input focus on a widget.
See also:
2025-2-13
Accessor gtk:widget-halign (object)
Syntax:
(gtk:widget-halign object) => align
(setf (gtk:widget-halign object) align)
Arguments:
object -- a gtk:widget object
align -- a gtk:align value
Details:
Accessor of the halign slot of the gtk:widget class. The gtk:widget-halign function returns the horizontal alignment of the widget. The (setf gtk:widget-halign) function sets the horizontal alignment.
See also:
2025-2-13
Accessor gtk:widget-has-default (object)
Syntax:
(gtk:widget-has-default object) => setting
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the widget is the default widget
Details:
Accessor of the has-default slot of the gtk:widget class. The gtk:widget-has-default function returns true if the widget is the current default widget within its toplevel, false otherwise.
See also:
2025-2-13
Accessor gtk:widget-has-focus (object)
Syntax:
(gtk:widget-has-focus object) => setting
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the widget has the input focus
Details:
Accessor of the has-focus slot of the gtk:widget class. The gtk:widget-has-focus function returns true if the widget has the global input focus.

See the gtk:widget-is-focus function for the difference between having the global input focus, and only having the focus within a toplevel.
See also:
2025-2-13
Accessor gtk:widget-has-tooltip (object)
Syntax:
(gtk:widget-has-tooltip object) => setting
(setf (gtk:widget-has-tooltip object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the emission of the "query-toolip" signal is enabled or disabled
Details:
Accessor of the has-tooltip slot of the gtk:widget class. Enables or disables the emission of the "query-tooltip" signal on the widget. A true value indicates that the widget can have a tooltip, in this case the widget will be queried using the "query-tooltip" signal to determine whether it will provide a tooltip or not.
See also:
2025-2-13
Accessor gtk:widget-height-request (object)
Syntax:
(gtk:widget-height-request object) => height
(setf (gtk:widget-height-request object) height)
Arguments:
object -- a gtk:widget object
height -- an integer for the height request
Details:
Accessor of the height-request slot of the gtk:widget class. See the gtk:widget-size-request function for details.
See also:
2025-2-13
Accessor gtk:widget-hexpand (object)
Syntax:
(gtk:widget-hexpand object) => setting
(setf (gtk:widget-hexpand object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether to expand horizontally
Details:
Accessor of the hexpand slot of the gtk:widget class. The gtk:widget-hexpand function gets whether the widget would like any available extra horizontal space. This function only looks at the own hexpand flag of the widget, rather than computing whether the entire widget tree rooted at this widget wants to expand.

The (setf gtk:widget-hexpand) function sets whether the widget would like any available extra horizontal space. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room.

By default, widgets automatically expand if any of their children want to expand. To see if a widget will automatically expand given its current children and state, call the gtk:widget-compute-expand function. A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on the gtk:widget class.

Setting the hexpand property explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, regardless of children. The override occurs because the gtk:widget-hexpand function sets the hexpand-set property, which causes the hexpand property of the widget to be used, rather than looking at children and widget state.
See also:
2025-2-13
Accessor gtk:widget-hexpand-set (object)
Syntax:
(gtk:widget-hexpand-set object) => setting
(setf (gtk:widget-hexpand-set object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether to use the hexpand property
Details:
Accessor of the hexpand-set slot of the gtk:widget class. The gtk:widget-hexpand-set function gets whether the gtk:widget-hexpand function has been used to explicitly set the expand flag on this widget.

The hexpand-set property will be set automatically when you call the gtk:widget-hexpand function to set the hexpand property, so the most likely reason to use the (setf gtk:widget-hexpand-set) function would be to unset an explicit expand flag.

If the hexpand property is set, then it overrides any computed expand value based on child widgets. If the hexpand property is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it is here for completeness and consistency.
See also:
2025-2-13
Accessor gtk:widget-layout-manager (object)
Syntax:
(gtk:widget-layout-manager object) => manager
(setf (gtk:widget-layout-manager object) manager)
Arguments:
object -- a gtk:widget object
manager -- a gtk:layout-manager object
Details:
Accessor of the layout-manager slot of the gtk:widget class. The gtk:widget-layout-manager function retrieves the layout manager used by the widget. The (setf gtk:widget-layout-manager) function sets the layout manager delegate instance that provides an implementation for measuring and allocating the children of the widget.
Examples:
Get the layout manager for a button and a grid:
(gtk:widget-layout-manager (make-instance 'gtk:button))
=> #<GTK:BIN-LAYOUT {1005DDB073}>
(gtk:widget-layout-manager (make-instance 'gtk:grid))
=> #<GTK:GRID-LAYOUT {1005DD9863}>    
See also:
2025-2-13
Accessor gtk:widget-margin-bottom (object)
Syntax:
(gtk:widget-margin-bottom object) => margin
(setf (gtk:widget-margin-bottom object) margin)
Arguments:
object -- a gtk:widget object
margin -- an integer for the margin on the bottom side of the widget
Details:
Accessor of the margin-bottom slot of the gtk:widget class. The gtk:widget-margin-bottom function gets the bottom marging of the widget. The (setf gtk:widget-margin-bottom) function sets the bottom margin.

This property adds margin outside of the normal size request of the widget. The margin will be added in addition to the size from the gtk:widget-size-request function for example.
See also:
2025-2-13
Accessor gtk:widget-margin-end (object)
Syntax:
(gtk:widget-margin-end object) => margin
(setf (gtk:widget-margin-end object) margin)
Arguments:
object -- a gtk:widget object
margin -- an integer for the margin on the end side of the widget, horizontally
Details:
Accessor of the margin-end slot of the gtk:widget class. The gtk:widget-margin-end function gets the value of the end margin of the widget. The (setf gtk:widget-margin-end) function sets the end margin.

This property supports left-to-right text directions. This property adds margin outside of the normal size request of the widget. The margin will be added in addition to the size from the gtk:widget-size-request function for example.
See also:
2025-2-13
Accessor gtk:widget-margin-start (object)
Syntax:
(gtk:widget-margin-start object) => margin
(setf (gtk:widget-margin-start object) margin)
Arguments:
object -- a gtk:widget object
margin -- an integer for the margin on the start side of the widget, horizontally
Details:
Accessor of the margin-start slot of the gtk:widget class. The gtk:widget-margin-start function returns the start margin of the widget. The (setf gtk:widget-margin-start) function sets the start margin.

This property supports left-to-right and right-to-left text directions. This property adds margin outside of the normal size request of the widget. The margin will be added in addition to the size from the gtk:widget-size-request function for example.
See also:
2025-2-13
Accessor gtk:widget-margin-top (object)
Syntax:
(gtk:widget-margin-top object) => margin
(setf (gtk:widget-margin-top object) margin)
Arguments:
object -- a gtk:widget object
margin -- an integer for the margin on the top side of the widget
Details:
Accessor of the margin-top slot of the gtk:widget class. The gtk:widget-margin-top function returns the top margin of widget. The (setf gtk:widget-margin-top) function sets the top margin.

This property adds margin outside of the normal size request of the widget. The margin will be added in addition to the size from the gtk:widget-size-request function for example.
See also:
2025-2-13
Accessor gtk:widget-name (object)
Syntax:
(gtk:widget-name object) => name
(setf (gtk:widget-name object) name)
Arguments:
object -- a gtk:widget object
name -- a string for the name of the widget
Details:
Accessor of the name slot of the gtk:widget class. The gtk:widget-name function retrieves the name of the widget. The (setf gtk:widget-name) function sets the name.

Widgets can be named, which allows you to refer to them from a CSS file. You can apply a style to widgets with a particular name in the CSS file. Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice.
See also:
2025-2-13
Accessor gtk:widget-opacity (object)
Syntax:
(gtk:widget-opacity object) => opacity
(setf (gtk:widget-opacity object) opacity)
Arguments:
object -- a gtk:widget object
opacity -- a double float for the opacity of the widget
Details:
Accessor of the opacity slot of the gtk:widget class. The gtk:widget-opacity function fetches the requested opacity for the widget. The (setf gtk:widget-opacity) function request the widget to be rendered partially transparent, with opacity 0.0 being fully transparent and 1.0 fully opaque.

Opacity works on both toplevel widgets and child widgets, although there are some limitations. For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this has any effect only on X displays with a compositing manager, see the gdk:display-is-composited function. On Windows and Wayland it should always work, although setting an opacity after the window has been shown may cause some flicker.

Note that the opacity is inherited through inclusion. If you set a toplevel widget to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel widget. The opacity value itself is not inherited by child widgets, since that would make widgets deeper in the hierarchy progressively more translucent. As a consequence, gtk:popover and other gtk:native widgets with their own surface will use their own opacity value, and thus by default appear non-translucent, even if they are attached to a toplevel widget that is translucent.
See also:
2025-2-13
Accessor gtk:widget-overflow (object)
Syntax:
(gtk:widget-overflow object) => overflow
(setf (gtk:widget-overflow object) overflow)
Arguments:
object -- a gtk:widget object
overflow -- a value of the gtk:overflow enumeration
Details:
Accessor of the overflow slot of the gtk:widget class. The gtk:widget-overflow function returns the overflow value of the widget. The (setf gtk:widget-overflow) function sets how the widget treats content that is drawn outside the content area of the widget. See the definition of the gtk:overflow enumeration for details.

This setting is provided for widget implementations and should not be used by application code. The default value is :visible.
See also:
2025-2-13
Accessor gtk:widget-parent (object)
Syntax:
(gtk:widget-parent object) => parent
Arguments:
object -- a gtk:widget object
parent -- a parent gtk:widget object
Details:
Accessor of the parent slot of the gtk:widget class. The gtk:widget-parent function returns the parent widget of the widget.
Notes:
The parent property is not writable. Use the gtk:widget-set-parent function if you need to set a parent widget in a widget implementation.
See also:
2025-2-13
Accessor gtk:widget-receives-default (object)
Syntax:
(gtk:widget-receives-default object) => setting
(setf (gtk:widget-receives-default object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the widget will receive the default action
Details:
Accessor of the receives-default slot of the gtk:widget class. The gtk:widget-receives-default function determines whether the widget is alyways treated as default widget within its toplevel when it has the focus, even if another widget is the default. The (setf gtk:widget-receives-default) function specifies whether the widget will be treated as the default widget.
See also:
2025-2-13
Accessor gtk:widget-root (object)
Syntax:
(gtk:widget-root object) => root
Arguments:
object -- a gtk:widget object
root -- a gtk:root root widget
Details:
The gtk:widget-root function returns the gtk:root widget of the widget. This function will return nil if the widget is not contained inside a widget tree with a root widget. The gtk:root widget will return itself here. See the gtk:window-destroy function for an example of how this function can be used in a signal handler to get the toplevel window.
See also:
2025-2-13
Accessor gtk:widget-scale-factor (object)
Syntax:
(gtk:widget-scale-factor object) => scale
Arguments:
object -- a gtk:widget object
scale -- an integer for the scale factor
Details:
The gtk:widget-scale-factor function retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2).
See also:
2025-2-13
Accessor gtk:widget-sensitive (object)
Syntax:
(gtk:widget-sensitive object) => setting
(setf (gtk:widget-sensitive object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether the widget responds to input
Details:
Accessor of the sensitive slot of the gtk:widget class. The gtk:widget-sensitive function returns the sensitivity of the widget. The (setf gtk:widget-sensitive) function sets the sensitivity.

A widget is sensitive if the user can interact with it. Insensitive widgets are "grayed out" and the user cannot interact with them. Insensitive widgets are known as "inactive", "disabled", or "ghosted" in some other toolkits.

The effective sensitivity of a widget is however determined by both its own and its parent sensitivity of the widget. See the gtk:widget-is-sensitive function.
See also:
2025-2-13
Accessor gtk:widget-tooltip-markup (object)
Syntax:
(gtk:widget-tooltip-markup object) => markup
(setf (gtk:widget-tooltip-markup object) markup)
Arguments:
object -- a gtk:widget object
markup -- a string for the text of the tooltip
Details:
Accessor of the tooltip-markup slot of the gtk:widget class. The gtk:widget-tooltip-markup function gets the contents of the tooltip. The (setf gtk:widget-tooltip-markup) function sets markup as the contents of the tooltip, which is marked up with the Pango text markup language.

This function will take care of setting the has-tooltip property to true and of the default handler for the "query-tooltip" signal.

See also the tooltip-markup property and the gtk:tooltip-set-markup function.
See also:
2025-2-13
Accessor gtk:widget-tooltip-text (object)
Syntax:
(gtk:widget-tooltip-text object) => text
(setf (gtk:widget-tooltip-text object) text)
Arguments:
object -- a gtk:widget object
text -- a string for the text of the tooltip
Details:
Accessor of the tooltip-text slot of the gtk:widget class. The gtk:widget-tooltip-text function gets the contents of the tooltip. The (setf gtk:widget-tooltip-text) function sets text as the contents of the tooltip.

This function will take care of setting the has-tooltip property to true and of the default handler for the "query-tooltip" signal.

See also the tooltip-text property and the gtk:tooltip-set-text function.
See also:
2025-2-13
Accessor gtk:widget-valign (object)
Syntax:
(gtk:widget-valign object) => align
(setf (gtk:widget-valign object) align)
Arguments:
object -- a gtk:widget object
align -- a value of the gtk:align enumeration
Details:
Accessor of the valign slot of the gtk:widget class. The gtk:widget-valign function gets the vertical alignment of the widget. The (setf gtk:widget-valign) function sets the vertical alignment.
See also:
2025-2-13
Accessor gtk:widget-vexpand (object)
Syntax:
(gtk:widget-vexpand object) => setting
(setf (gtk:widget-vexpand object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether to expand vertically
Details:
Accessor of the vexpand slot of the gtk:widget class. The gtk:widget-vexpand function gets whether the widget would like any available extra vertical space. The (setf gtk:widget-vexpand) function sets whether the widget would like any available extra vertical space.

See the gtk:widget-hexpand function for more details.
See also:
2025-2-13
Accessor gtk:widget-vexpand-set (object)
Syntax:
(gtk:widget-vexpand-set object) => setting
(setf (gtk:widget-vexpand-set object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether to use the vexpand property
Details:
Accessor of the vexpand-set slot of the gtk:widget class. The gtk:widget-vexpand-set function gets whether the (setf gtk:widget-vexpand) function has been used to explicitly set the expand flag on this widget. The (setf gtk:widget-vexpand-set) function sets whether the vexpand property will be used.

See the gtk:widget-hexpand-set function for more details.
See also:
2025-2-13
Accessor gtk:widget-visible (object)
Syntax:
(gtk:widget-visible object) => setting
(setf (gtk:widget-visible object) setting)
Arguments:
object -- a gtk:widget object
setting -- a boolean whether widget is visible
Details:
Accessor of the visible slot of the gtk:widget class. The gtk:widget-visible function determines whether the widget is visible. The (setf gtk:widget-visible) function sets the visibility state. Note that this does not take into account whether the parent of the widget is also visible or the widget is obscured in any way.

If you want to take into account whether the parent of the widget is also marked as visible, use the gtk:widget-is-visible function.
See also:
2025-2-13
Accessor gtk:widget-width-request (object)
Syntax:
(gtk:widget-width-request object) => width
(setf (gtk:widget-width-request object) width)
Arguments:
object -- a gtk:widget object
width -- an integer for the width request
Details:
Accessor of the width-request slot of the gtk:widget class. See the gtk:widget-size-request function for details.
See also:
2025-2-13
Function gtk:widget-in-destruction (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget is being destroyed.
Details:
Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work.
See also:
#2025-2-13
Function gtk:widget-show (widget)
Arguments:
widget -- a gtk:widget object
Details:
Flags a widget to be displayed. Any widget that is not shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped. Other shown widgets are realized and mapped when their toplevel container is realized and mapped.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-visible function instead.
See also:
2025-2-13
Function gtk:widget-hide (widget)
Arguments:
widget -- a gtk:widget object
Details:
Reverses the effects of the gtk:widget-show function. This is causing the widget to be hidden, so it is invisible to the user.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-visible function instead.
See also:
2025-2-13
Function gtk:widget-map (widget)
Arguments:
widget -- a gtk:widget object
Details:
Causes a widget to be mapped if it is not already. This function is only for use in widget implementations.
See also:
2025-2-13
Function gtk:widget-unmap (widget)
Arguments:
widget -- a gtk:widget object
Details:
Causes a widget to be unmapped if it is currently mapped. This function is only for use in widget implementations.
See also:
2025-2-13
Function gtk:widget-mapped (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if the widget is mapped, false otherwise.
Details:
This function determines whether the widget is mapped.
See also:
2025-2-13
Function gtk:widget-realize (widget)
Arguments:
widget -- a gtk:widget object
Details:
Creates the GDK resources associated with a widget. Normally realization happens implicitly. If you show a widget and all its parent containers, then the widget will be realized and mapped automatically.

Realizing a widget requires all the parent widgets of the widget to be realized. Calling the gtk:widget-realize function realizes the parents of the widget in addition to the widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen.

This function is primarily used in widget implementations, and is not very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as the "realize" signal.
See also:
2025-2-13
Function gtk:widget-unrealize (widget)
Arguments:
widget -- a gtk:widget object
Details:
Causes a widget to be unrealized. Frees all GDK resources associated with the widget. This function is only useful in widget implementations.
See also:
2025-2-13
Function gtk:widget-realized (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if the widget is realized, false otherwise.
Details:
This function determines whether the widget is realized.
See also:
2025-2-13
Function gtk:widget-queue-draw (widget)
Arguments:
widget -- a gtk:widget object
Details:
Schedules the widget to be redrawn in the paint phase of the current or the next frame.
See also:
2025-2-13
Function gtk:widget-queue-resize (widget)
Arguments:
widget -- a gtk:widget object
Details:
Flags a widget to have its size renegotiated. Should be called when a widget for some reason has a new size request. For example, when you change the text in a label, the gtk:label widget queues a resize to ensure there is enough space for the new text.

This function is only for use in widget implementations.
Notes:
You cannot call the gtk:widget-queue-resize function on a widget from inside its implementation of the size_allocate virtual method. Calls to this function from inside the virtual method will be silently ignored.
See also:
#2025-2-13
Function gtk:widget-queue-allocate (widget)
Arguments:
widget -- a gtk:widget object
Details:
Flags the widget for a rerun of the size_allocate () virtual function. Use this function instead of the gtk:widget-queue-resize function when the size request of the widget did not change but it wants to reposition its contents. An example user of this function is the gtk:widget-halign function.

This function is only for use in widget implementations.
See also:
2025-2-13
Function gtk:widget-frame-clock (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gdk:frame-clock object, or nil if widget is unrealized.
Details:
Obtains the frame clock for a widget. The frame clock is a global "ticker" that can be used to drive animations and repaints. The most common reason to get the frame clock is to call the gdk:frame-clock-frame-time function, in order to get a time to use for animating. For example you might record the start of the animation with an initial value from the gdk:frame-clock-frame-time function, and then update the animation by calling the gdk:frame-clock-frame-time function again during each repaint.

The gdk:frame-clock-request-phase function will result in a new frame on the clock, but will not necessarily repaint any widgets. To repaint a widget, you have to use the gtk:widget-queue-draw function which invalidates the widget, thus scheduling it to receive a draw on the next frame. The gtk:widget-queue-draw function will also end up requesting a frame on the appropriate frame clock.

A frame clock of the widget will not change while the widget is mapped. Reparenting a widget, which implies a temporary unmap, can change the frame clock of the widget.

Unrealized widgets do not have a frame clock.
See also:
2025-2-13
Callback gtk:tick-callback
Syntax:
lambda (widget clock) => result
Arguments:
widget -- a gtk:widget object
clock -- a gdk:frame-clock object for the widget, same as calling the gtk:widget-frame-clock function
result -- true, if the tick callback function should continue to be called, false, if the tick callback function should be removed
Details:
Callback type for adding a function to update animations. See the gtk:widget-add-tick-callback function.
See also:
2025-3-1
Function gtk:widget-add-tick-callback (widget func)
Arguments:
widget -- a gtk:widget object
func -- a gtk:tick-callback callback function to call for updating animations
Returns:
The unsigned integer ID for the connection of this callback function, remove the callback function by passing it to the gtk:widget-remove-tick-callback function.
Details:
Queues an animation frame update and adds a callback function to be called before each frame. Until the tick callback function is removed, it will be called frequently, usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower. For this reason, it is most suitable for handling graphics that change every frame or every few frames. The tick callback function does not automatically imply a relayout or repaint. If you want a repaint or relayout, and are not changing widget properties that would trigger that, for example, changing the text of a gtk:label widget, then you will have to call the gtk:widget-queue-resize function or the gtk:widget-queue-draw function yourself.

The gdk:frame-clock-frame-time function should generally be used for timing continuous animations and the gdk:frame-timings-predicted-presentation-time function if you are trying to display isolated frames at particular times.

This is a more convenient alternative to connecting directly to the "update" signal of the gdk:frame-clock object, since you do not have to worry about when the gdk:frame-clock object is assigned to a widget.
See also:
2025-3-1
Function gtk:widget-remove-tick-callback (widget id)
Arguments:
widget -- a gtk:widget object
id -- an unsigned integer for the ID returned by the gtk:widget-add-tick-callback function
Details:
Removes a tick callback function previously registered with the gtk:widget-add-tick-callback function.
See also:
2025-3-1
Function gtk:widget-size-allocate (widget allocation baseline)
Arguments:
widget -- a gtk:widget object
allocation -- a gdk:rectangle instance for the position and size to be allocated to widget
baseline -- an integer for the baseline of the child widget, or -1
Details:
Allocates the widget with a transformation that translates the origin to the position in allocation. This is a simple form of the gtk:widget-allocate function.
See also:
2025-2-13
Function gtk:widget-allocate (widget width height baseline transform)
Arguments:
widget -- a gtk:widget object
width -- an integer for the new width of the widget
height -- an integer for the new height of the widget
baseline -- an integer for the baseline of the widget, or -1
transform -- a gsk:transform object to be applied to the widget
Details:
This function is only used by gtk:widget subclasses, to assign a size, position and (optionally) baseline to their child widgets. In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the minimum size of the widget, as well as at least 0×0 in size. For a version that does not take a transform, see the gtk:widget-size-allocate function.
See also:
2025-2-13
Function gtk:widget-class-add-shortcut (gtype shortcut)
Arguments:
gtype -- a g:type-t type ID for the widget class to add the shortcut to
shortcut -- a gtk:shortcut object to add
Details:
Installs a shortcut for the widget class of g:type-t type. Every instance created for the widget class or its subclasses will inherit this shortcut and trigger it.

Shortcuts added this way will be triggered in the :bubble propagation phase, which means they may also trigger if child widgets have focus.

This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed.
See also:
#2025-2-13
Function gtk:widget-class-layout-manager-type (gtype)
Syntax:
(gtk:widget-class-layout-manager-type gtype) => value
(setf (gtk:widget-class-layout-manager-type gtype) value)
Arguments:
gtype -- a g:type-t type ID for the widget class
value -- a g:type-t type ID for the object type that implements the gtk:layout-manager object for the widget class of gtype type
Details:
The gtk:widget-class-layout-manager-type function retrieves the type of the gtk:layout-manager object used by the widget of the given gtype type. The gtk:widget-class-layout-manager-type function sets the type to be used for creating layout managers for widgets of gtype type.

This function should only be called from class init functions of widgets.
Examples:
(gtk:widget-class-layout-manager-type "GtkBox")
=> #<GTYPE :name "GtkBoxLayout" :id 99175136080768>
(gtk:widget-class-layout-manager-type "GtkButton")
=> #<GTYPE :name "GtkBinLayout" :id 99175136080464>
(gtk:widget-class-layout-manager-type "GtkWindow")
=> NIL    
See also:
2025-2-13
Function gtk:widget-activate (widget)
Arguments:
widget -- a gtk:widget object that is activatable
Returns:
True if the widget was activatable.
Details:
For widgets that can be "activated", buttons, menu items, and so on, this function activates them. Activation is what happens when you press the Enter key on a widget during key navigation. If the widget is not activatable, the function returns false.
See also:
2025-2-13
Function gtk:widget-is-focus (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if the widget is the focus widget.
Details:
Determines if the widget is the focus widget within its toplevel. This does not mean that the has-focus property is necessarily set. The has-focus property will only be set if the toplevel widget additionally has the global input focus.
See also:
2025-2-13
Function gtk:widget-grab-focus (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if the focus is now inside widget.
Details:
Causes the widget to have the keyboard focus for the gtk:window widget it is inside.

If the widget is not focusable, or its grab_focus() implementation cannot transfer the focus to a descendant of the widget that is focusable, it will not take focus and false will be returned.

Calling the gtk:widget-grab-focus function on an already focused widget is allowed, should not have an effect, and returns true.
See also:
#2025-2-13
Function gtk:widget-set-parent (widget parent)
Arguments:
widget -- a gtk:widget object
parent -- a parent gtk:widget object
Details:
Sets parent as the parent widget of widget. This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. The opposite function is the gtk:widget-unparent function.

This function is useful only when implementing subclasses of the gtk:widget object.
Notes:
The parent property is not writable. You have to use this function to set the parent widget.
See also:
2025-2-13
Function gtk:widget-unparent (widget)
Arguments:
widget -- a gtk:widget object
Details:
Dissociate the widget from its parent. This function is only for use in widget implementations, typically in dispose.
See also:
2025-2-13
Function gtk:widget-native (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:native widget of widget, or nil.
Details:
Returns the gtk:native widget that contains widget, or nil if the widget is not contained inside a widget tree with a native ancestor. The gtk:native widget will return itself here.
See also:
2025-2-13
Function gtk:widget-ancestor (widget gtype)
Arguments:
widget -- a gtk:widget object
gtype -- an ancestor g:type-t type ID
Returns:
The gtk:widget ancestor widget, or nil if not found.
Details:
Gets the first ancestor of the widget with type gtype. For example, the call (gtk:widget-ancestor widget "GtkBox") gets the first gtk:box widget that is an ancestor of the widget.

Note that unlike the gtk:widget-is-ancestor function, the gtk:widget-ancestor function considers the widget to be an ancestor of itself.
See also:
2025-2-13
Function gtk:widget-is-ancestor (widget ancestor)
Arguments:
widget -- a gtk:widget object
ancestor -- another gtk:widget object
Returns:
True if ancestor contains the widget as a child, grandchild, great grandchild, and so on.
Details:
Determines whether the widget is somewhere inside ancestor, possibly with intermediate containers.
See also:
2025-2-13
Function gtk:widget-translate-coordinates (src dst xsrc ysrc)
Syntax:
(gtk:widget-translate-coordinates src dest xsrc ysrc) => xdest, ydest
Arguments:
src -- a gtk:widget object
dest -- a gtk:widget object
xsrc -- an integer for the x position relative to src
ysrc -- an integer for the y position relative to src
Returns:
False if either the widget was not realized, or there was no common ancestor. Otherwise the x position and the y position relative to dest.
Details:
Translate coordinates relative to the allocation of src to coordinates relative to the allocations of dest. In order to perform this operation, both widgets must be realized, and must share a common toplevel.
Warning:
This function is deprecated since 4.12. Use the gtk:widget-compute-point function instead.
See also:
#2025-2-13
Function gtk:widget-add-controller (widget controller)
Arguments:
widget -- a gtk:widget object
controller -- a gtk:event-controller object that has not added to a widget yet
Details:
Adds the event controller to the widget so that it will receive events. You will usually want to call this function right after creating any kind of event controller.
See also:
2025-2-13
Function gtk:widget-remove-controller (widget controller)
Arguments:
widget -- a gtk:widget object
controller -- a gtk:event-controller object
Details:
Removes the event controller from the widget, so that it does not process events anymore. The event controller should not be used again.

Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function.
See also:
2025-2-13
Function gtk:widget-direction (widget)
Syntax:
(gtk:widget-direction widget) => direction
(setf (gtk:widget-direction widget) direction)
Arguments:
widget -- a gtk:widget object
direction -- a value of the gtk:text-direction enumeration
Details:
The gtk:widget-direction function gets the reading direction for the widget. The (setf gtk:widget-direction) function sets the reading direction.

This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitely visual rather than logical, such as buttons for text justification.

If the direction is set to the :none value, then the value set by the gtk:widget-default-direction function will be used.
See also:
#2025-2-13
Function gtk:widget-default-direction ()
Syntax:
(gtk:widget-default-direction) => direction
(setf (gtk:widget-default-direction) direction)
Arguments:
direction -- a value of the gtk:text-direction enumeration for the default direction, this cannot be :none.
Details:
The gtk:widget-default-direction function obtains the current default reading direction. The (setf gtk:widget-default-direction) function sets the default reading direction for widgets where the direction has not been explicitly set by the gtk:widget-direction function.
See also:
#2025-2-13
Function gtk:widget-create-pango-context (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The new pango:context object.
Details:
Creates a new Pango context with the appropriate font map, font description, and base direction for drawing text for this widget. See also the gtk:widget-pango-context function.
See also:
2025-2-13
Function gtk:widget-pango-context (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The pango:context object for the widget.
Details:
Gets a Pango context with the appropriate font map, font description, and base direction for this widget. Unlike the Pango context returned by the gtk:widget-create-pango-context function, this Pango context is owned by the widget, it can be used until the screen for the widget changes or the widget is removed from its toplevel, and will be updated to match any changes to the attributes of the widget.

If you create and keep a pango:layout object using this Pango context, you must deal with changes to the Pango context by calling the pango:layout-context-changed function on the Pango layout in response to the "style-updated" and "direction-changed" signals for the widget.
See also:
2025-2-13
Function gtk:widget-font-options (widget)
Syntax:
(gtk:widget-font-options widget) => options
(setf (gtk:widget-font-options widget) options)
Arguments:
widget -- a gtk:widget object
options -- a cairo:font-options-t instance, or nil to unset any previously set default font options
Details:
The gtk:widget-font-options function returns the font options used for Pango rendering. The (setf gtk:widget-font-options) function sets the font options. When not set, the default font options for the GDK screen will be used.
Warning:
Deprecated since 4.16. Do not use this function in newly written code.
See also:
#2025-2-13
Function gtk:widget-font-map (widget)
Syntax:
(gtk:widget-font-map widget) => fontmap
(setf (gtk:widget-font-map widget) fontmap)
Arguments:
widget -- a gtk:widget object
fontmap -- a pango:font-map object, or nil to unset any previously set font map
Details:
The gtk:widget-font-map function gets the font map that has been set. The (setf gtk:widget-font-map) function sets the font map to use for Pango rendering. When not set, the widget will inherit the font map from its parent.
See also:
#2025-2-13
Function gtk:widget-create-pango-layout (widget text)
Arguments:
widget -- a gtk:widget object
text -- a string for the text to set on the Pango layout, can be nil
Returns:
The new pango:layout object.
Details:
Creates a new pango:layout object with the appropriate font map, font description, and base direction for drawing text for this widget.

If you keep a pango:layout object created in this way around, in order to notify the layout of changes to the base direction or font of this widget, you must call the pango:layout-context-changed function in response to the "style-updated" and "direction-changed" signals for the widget.
See also:
2025-2-13
Function gtk:widget-set-cursor-from-name (widget name)
Arguments:
widget -- a gtk:widget object
name -- a string for the name of the cursor or nil to use the default cursor
Details:
Sets a named cursor to be shown when pointer devices point towards widget. This is a utility function that creates a cursor via the gdk:cursor-new-from-name function and then sets it on widget with the gtk:widget-cursor function. See those two functions for details.

On top of that, this function allows name to be nil, which will do the same as calling the gtk:widget-cursor function with a nil cursor.
See also:
2025-2-13
Function gtk:widget-class-accessible-role (gtype)
Syntax:
(gtk:widget-class-accessible-role gtype) => role
(setf (gtk:widget-class-accessible-role gtype) role)
Arguments:
gtype -- a g:type-t type ID
role -- a gtk:accessible-role value
Details:
The gtk:widget-class-accessible-role function gets the accessible role used by the given widget class. The (setf gtk:widget-class-accessible-role) function sets the accessible role. Different accessible roles have different states, and are rendered differently by assistive technologies.
See also:
2025-2-13
Function gtk:widget-child-focus (widget direction)
Arguments:
widget -- a gtk:widget object
direction -- a gtk:direction-type value for the direction of focus movement
Returns:
True if the focus ended up inside widget.
Details:
Called by widgets as the user moves around the window using keyboard shortcuts. The direction argument indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward).

This function calls the Gtk.WidgetClass.focus() virtual function. Widgets can override the virtual function in order to implement appropriate focus behavior.

The default Gtk.WidgetClass.focus() virtual function for a widget should return true if moving in direction left the focus on a focusable location inside that widget, and false if moving in direction moved the focus outside the widget. When returning true, widgets normally call the gtk:widget-grab-focus function to place the focus accordingly. When returning false, they do not modify the current focus location.

This function is used by custom widget implementations. If you are writing an application, you would use the gtk:widget-grab-focus function to move the focus to a particular widget.
See also:
#2025-2-13
Function gtk:widget-child-visible (widget)
Syntax:
(gtk:widget-child-visible widget) => visible
(setf (gtk:widget-child-visible widget) visible)
Arguments:
widget -- a gtk:widget object
visible -- if true, widget should be mapped along with its parent
Details:
The gtk:widget-child-visible function returns true if the widget is mapped with the parent. The (setf gtk:widget-child-visible) function sets whether the widget should be mapped along with its parent when its parent is mapped and the widget has been shown with the gtk:widget-show function.

The child visibility can be set for the widget before it is added to a container with the gtk:widget-parent function, to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of true when the widget is removed from a container.

Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself.

This function is only useful for container implementations and never should be called by an application.
See also:
#2025-2-13
Function gtk:widget-settings (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The relevant gtk:settings object.
Details:
Gets the settings object holding the settings used for this widget. Note that this function can only be called when the widget is attached to a toplevel, since the settings object is specific to a particular gdk:display object. If you want to monitor the widget for changes in its settings, connect to the notify::display signal.
See also:
2025-2-13
Function gtk:widget-clipboard (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The appropriate gdk:clipboard object.
Details:
Gets the clipboard object for the widget. This is an utility function to get the clipboard object for the gdk:display object that the widget is using. Note that this function always works, even when the widget is not realized yet.
See also:
2025-2-13
Function gtk:widget-primary-clipboard (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gdk:clipboard object with the appropriate clipboard object.
Details:
This is a utility function to get the primary clipboard object for the gdk:display object that widget is using. Note that this function always works, even when the widget is not realized yet.
See also:
#2025-2-13
Function gtk:widget-display (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gdk:display object for the toplevel of this widget.
Details:
Gets the display for the toplevel window associated with the widget. This function can only be called after the widget has been added to a widget hierarchy with a gtk:window widget at the top. In general, you should only create display specific resources when a widget has been realized.
See also:
2025-2-13
Function gtk:widget-size-request (widget)
Syntax:
(gtk:widget-size-request object) => width, height
(setf (gtk:widget-size-request object) (list width height))
Arguments:
object -- a gtk:widget object
width -- an integer for the width
height -- an integer for the height
Details:
The gtk:widget-size-request function gets the size request of the widget. A value of -1 returned in width or height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. To get the size a widget will actually request, call the gtk:widget-measure function instead of this function.

The (setf gtk:widget-size-request) function sets the minimum size of a widget. That is, the size request of the widget will be width by height. You can use this function to force a widget to be either larger or smaller than it normally would be.

In most cases, the gtk:window-default-size function is a better choice for toplevel windows than this function. Setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request.

Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it is basically impossible to hardcode a size that will always be correct.

The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested.

If the size request in a given direction is -1 (unset), then the "natural" size request of the widget will be used instead.

The size request set here does not include any margin from the margin-start, margin-end, margin-top, and margin-bottom properties, but it does include pretty much all other padding or border properties set by any subclass of the gtk:widget class.
See also:
2025-2-13
Function gtk:widget-list-mnemonic-labels (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The list of gtk:widget objects with the mnemonic labels.
Details:
Returns a list of the widgets, normally labels, for which this widget is the target of a mnemonic. See for example the gtk:label-mnemonic-widget function for more information about mnemonic labels.
Examples:
(setq button (gtk:button-new-with-mnemonic "_Hello"))
=> #<GTK-BUTTON {C2794C9}>
(gtk:widget-list-mnemonic-labels button)
=> (#<GTK-LABEL {C292FE1}>)    
See also:
2025-2-13
Function gtk:widget-add-mnemonic-label (widget label)
Arguments:
widget -- a gtk:widget object
label -- a gtk:widget object that acts as a mnemonic label for widget
Details:
Adds a widget to the list of mnemonic labels for this widget. See the gtk:widget-list-mnemonic-labels function for a list of mnemonic labels for this widget.

Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by using a connection to the "destroy" signal or a weak notifier.
See also:
2025-2-13
Function gtk:widget-remove-mnemonic-label (widget label)
Arguments:
widget -- a gtk:widget object
label -- a gtk:widget object that was previously set as a mnemonic label for widget
Details:
Removes a widget from the list of mnemonic labels for this widget. See the gtk:widget-list-mnemonic-labels function for a list of mnemonic labels for the widget. The widget must have previously been added to the list with the gtk:widget-add-mnemonic-label function.
See also:
2025-2-13
Function gtk:widget-mnemonic-activate (widget cycling)
Arguments:
widget -- a gtk:widget object
cycling -- true if there are other widgets with the same mnemonic
Returns:
True if the signal has been handled.
Details:
Emits the "mnemonic-activate" signal. The default handler for this signal activates the widget if cycling is false, and just grabs the focus if cycling is true.
See also:
2025-2-13
Function gtk:widget-error-bell (widget)
Arguments:
widget -- a gtk:widget object
Details:
Notifies the user about an input-related error on this widget. If the gtk-error-bell setting is true, it calls the gdk:surface-beep function, otherwise it does nothing.

Note that the effect of the gdk:surface-beep function can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.
See also:
2025-2-3
Function gtk:widget-keynav-failed (widget direction)
Arguments:
widget -- a gtk:widget object
direction -- a gtk:direction-type value for the direction of focus movement
Returns:
True if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).
Details:
Emits the "notify::keynav-failed" signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary.

The return value of this function should be interpreted in a way similar to the return value of gtk:widget-child-focus function. When true is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When false is returned, the caller should continue with keyboard navigation outside the widget, for example, by calling the gtk:widget-child-focus function on the toplevel of the widget.

The default "keynav-failed" signal handler returns false for the :tab-forward and :tab-backward values of the gtk:direction-type enumeration. For the other values of the gtk:direction-type enumeration it returns true.

Whenever the default handler returns true, it also calls the gtk:widget-error-bell function to notify the user of the failed keyboard navigation.

A use case for providing an own implementation of the "keynav-failed" signal handler (either by connecting to it or by overriding it) would be a row of gtk:entry widgets where the user should be able to navigate the entire row with the cursor keys, as for example, known from user interfaces that require entering license keys.
See also:
2025-2-13
Function gtk:widget-trigger-tooltip-query (widget)
Arguments:
widget -- a gtk:widget object
Details:
Triggers a tooltip query on the display where the toplevel of widget is located.
See also:
#2025-2-13
Function gtk:widget-allocated-width (widget)
Arguments:
widget -- a gtk:widget object to query
Returns:
The integer with the width of the widget.
Details:
Returns the width that has currently been allocated to widget.
Notes:
The gtk:widget-allocated-width function is equivalent to the call
(gdk:rectangle-width (gtk:widget-allocation widget))    
Warning:
This function is deprecated since 4.12. Use the gtk:widget-width function instead.
See also:
#2025-2-13
Function gtk:widget-allocated-height (widget)
Arguments:
widget -- a gtk:widget object to query
Returns:
The integer with the height of the widget.
Details:
Returns the height that has currently been allocated to widget.
Notes:
The gtk:widget-allocated-height function is equivalent to the call
(gdk:rectangle-height (gtk:widget-allocation widget))    
Warning:
This function is deprecated since 4.12. Use the gtk:widget-height function instead.
See also:
#2025-2-13
Function gtk:widget-allocation (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gdk:rectangle instance with the allocation.
Details:
Retrieves the allocation of the widget. Note, when implementing a layout container: an allocation of the widget will be its "adjusted" allocation, that is, the parent of the widget typically calls the gtk:widget-size-allocate function with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. The gtk:widget-allocation function returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the gtk:widget-size-allocate allocation, however.

So a layout container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned.
Notes:
In the Lisp binding to GTK this function does not return an allocation of type GtkAllocation, but a gdk:rectangle instance. In the C implementation the GtkAllocation type is a synonym for the gdk:rectangle type.
Warning:
This function is deprecated since 4.12. Use the gtk:widget-compute-bounds, gtk:widget-width, or gtk:widget-height functions instead.
See also:
#2025-2-15
Function gtk:widget-allocated-baseline (widget)
Arguments:
widget -- a gtk:widget object to query
Returns:
The integer with the baseline of the widget, or -1 if none.
Details:
Returns the baseline that has currently been allocated to the widget.
Warning:
This function is deprecated since 4.12. Use the gtk:widget-baseline function instead.
See also:
#2025-2-15
Function gtk:widget-width (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The integer with the width of widget.
Details:
Returns the content width of the widget, as passed to its size allocate implementation. This is the size you should be using in the GtkWidgetClass.snapshot() virtual function. For pointer events, see the gtk:widget-contains function.
See also:
2025-2-15
Function gtk:widget-height (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The integer with the height of widget.
Details:
Returns the content width of the widget, as passed to its size allocate implementation. This is the size you should be using in the GtkWidgetClass.snapshot() virtual function. For pointer events, see the gtk:widget-contains function.
See also:
2025-2-15
Function gtk:widget-size (widget orientation)
Arguments:
widget -- a gtk:widget object
orientation -- a gtk:orientation value for the orientation to query
Returns:
The integer with the size of the widget in the given orientation.
Details:
Returns the content width or height of the widget, depending on the given orientation. This is equivalent to calling the gtk:widget-width function for the :horizontal value or the gtk:widget-height function for the :vertical value, but can be used when writing orientation independent code, such as when implementing gtk:orientable widgets.
See also:
#2025-2-15
Function gtk:widget-baseline (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The integer with the baseline of widget, or -1 if none.
Details:
Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers for the GtkWidgetClass.snapshot() virtual function, and when allocating child widgets in the GtkWidgetClass.size_allocate() virtual function.

Since 4.12
See also:
2025-2-15
Function gtk:widget-compute-bounds (widget target bounds)
Arguments:
widget -- a gtk:widget object
target -- a gtk:widget target widget
bounds -- a graphene:rect-t instance for the result
Returns:
The graphene:rect-t instance with the bounds, or nil.
Details:
Computes the bounds for widget in the coordinate space of target. The bounds of the widget are the bounding box of the region that it is expected to draw in. See the coordinate system overview to learn more.

If the operation is successful, bounds is returned. If widget has no bounds or the bounds cannot be expressed in the coordinate space of target, for example, if both widgets are in different windows, nil is returned and bounds is set to the zero rectangle.

It is valid for widget and target to be the same widget.
See also:
2025-2-15
Function gtk:widget-compute-transform (widget target transform)
Arguments:
widget -- a gtk:widget object
target -- a gtk:widget object for the target widget that the matrix will transform to
transform -- a graphene:matrix-t instance for the final transformation
Returns:
The graphene:matrix-t instance with the transformation, or nil if transform could not be computed, for example, when widget and target do not share a common ancestor. In that case transform gets set to the identity matrix.
Details:
Computes a matrix suitable to describe a transformation from the coordinate system of widget into the coordinate system of target.
See also:
#2025-2-15
Function gtk:widget-compute-point (widget target point out)
Arguments:
widget -- a gtk:widget object to query
target -- a gtk:widget object to transform into
point -- a graphene:point-t instance for a point in the coordinate sytem of widget
out -- a graphene:point-t instance for the corresponding coordinates in the coordinate system of target
Returns:
The graphene:point-t instance if the point could be determined, nil on failure, in this case, out is set to (0,0).
Details:
Translates the given point in the coordinates of widget to coordinates relative to the coordinate system of target. In order to perform this operation, both widgets must share a common root.
See also:
#2025-2-15
Function gtk:widget-contains (widget x y)
Arguments:
widget -- a gtk:widget object to query
x -- a number coerced to a double float for the x coordinate to test, relative to the origin of the widget
y -- a number coerced to a double float for the y coordinate to test, relative to the origin of the widget
Returns:
True if widget contains (x,y).
Details:
Tests if the point at (x,y) is contained in the widget. The coordinates for (x,y) must be in widget coordinates, so (0,0) is assumed to be the top left of the content area of the widget.
See also:
#2025-2-15
Function gtk:widget-pick (widget x y flags)
Arguments:
widget -- a gtk:widget object
x -- a number coerced to a double float for the x coordinate to test, relative to the origin of the widget
y -- a number coerced to a double float for the y coordinate to test, relative to the origin of the widget
flags -- a gtk:pick-flags value to influence what is picked
Returns:
The descendant gtk:widget object at the given coordinate or nil if none.
Details:
Finds the descendant of widget, including widget itself, closest to the screen at the point (x,y). The point must be given in widget coordinates, so (0,0) is assumed to be the top left of the content area of the widget.

Usually widgets will return nil if the given coordinate is not contained in widget checked via the gtk:widget-contains function. Otherwise they will recursively try to find a child that does not return nil. Widgets are however free to customize their picking algorithm.

This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events.
See also:
#2025-2-15
Function gtk:widget-focus-child (widget)
Arguments:
widget -- a gtk:widget object
child -- a gtk:widget object for a direct child widget, or nil to unset the focus child of widget
Details:
The gtk:widget-focus-child function returns the current focus child of widget. The (setf gtk:widget-focus-child) function sets child as the current focus child of widget. The previous focus child will be unset.

This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call the gtk:widget-grab-focus function on it.
See also:
#2025-2-15
Function gtk:widget-is-sensitive (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget is effectively sensitive.
Details:
Returns the widgets effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive.
See also:
#2025-2-15
Function gtk:widget-is-visible (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget and all its parents are visible.
Details:
Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also the gtk:widget-visible function.
See also:
#2025-2-15
Function gtk:widget-state-flags (widget)
Syntax:
(gtk:widget-state-flags widget) => flags
(setf (gtk:widget-state-flags widget clear) flags)
Arguments:
widget -- a gtk:widget object
flags -- a gtk:state-flags value
clear -- an optional boolean whether to clear the state flags before turning on flags
Details:
The gtk:widget-state-flags function returns the widget state as a flag set. The (setf gtk:widget-state-flags) function sets the widget state flags.

It is worth mentioning that the effective :insensitive state will be returned, that is, also based on parent insensitivity, even if widget itself is sensitive.

Also note that if you are looking for a way to obtain the gtk:state-flags values to pass to a gtk:style-context function, you should look at the gtk:style-context-state function.

This function is for use in widget implementations. Turns on flag values in the current widget state, insensitive, prelighted, and so on.
See also:
2025-2-15
Function gtk:widget-unset-state-flags (widget flags)
Arguments:
widget -- a gtk:widget object
flags -- a gtk:state-flags value to turn off
Details:
Turns off flag values for the current widget state, insensitive, prelighted, and so on. See the gtk:widget-state-flags function.

This function is for use in widget implementations.
See also:
2025-2-15
Function gtk:widget-has-visible-focus (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget should display a focus rectangle.
Details:
Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function that takes into account whether focus indication should currently be shown in the toplevel window of widget. See the gtk:window-focus-visible function for more information about focus indication.

To find out if the widget has the global input focus, use the gtk:widget-has-focus function.
See also:
2025-2-15
Function gtk:widget-is-drawable (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget is drawable, false otherwise.
Details:
Determines whether the widget can be drawn to. A widget can be drawn to if it is mapped and visible.
See also:
#2025-2-15
Function gtk:widget-measure (widget orientation for-size)
Arguments:
widget -- a gtk:widget object
orientation -- a gtk:orientation value for the orientation to measure
for-size -- an integer for the size for the opposite of orientation, that is, if orientation is :horizontal, this is the height the widget should be measured with. The :vertical case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed.
Returns:
minimum -- an integer with the minimum size
natural -- an integer with the natural size
minimum-baseline -- an integer with the baseline position for the minimum size
natural-baseline -- an integer with the baseline position for the natural size
Details:
Measures widget in the orientation orientation and for the given for-size. As an example, if orientation is :horizontal and for-size is 300, this functions will compute the minimum and natural width of widget if it is allocated at a height of 300 pixels.
See also:
2025-2-15
Function gtk:widget-snapshot (widget snapshot)
Arguments:
widget -- a gtk:widget object
snapshot -- a gtk:snapshot object as passed to the widget, in particular, no calls to the gtk:snapshot-translate function or other transform calls should have been made
Details:
Calls the gtk:widget-snapshot virtual function for widget and its children when a new snapshot of widget has to be taken.
Notes:
This function is not exported from the C library and implemented for the Lisp API with the gtk:widget-snapshot-child function.
See also:
2025-2-15
Function gtk:widget-snapshot-child (widget child snapshot)
Arguments:
widget -- a gtk:widget object
child -- a gtk:widget child widget of widget
snapshot -- a gtk:snapshot object as passed to the widget, in particular, no calls to the gtk:snapshot-translate function or other transform calls should have been made
Details:
When a widget receives a call to the snapshot function, it must send synthetic gtk:widget-snapshot calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its gtk:widget-snapshot virtual function, calls the gtk:widget-snapshot-child function once for each child, passing in the snapshot the widget received.

The gtk:widget-snapshot-child function takes care of translating the origin of snapshot, and deciding whether the child needs to be snapshot.

This function does nothing for children that implement the gtk:native interface.
See also:
2025-2-15
Function gtk:widget-next-sibling (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:widget sibling widget.
Details:
Returns the next sibling of the widget. This API is primarily meant for widget implementations.
See also:
2025-2-15
Function gtk:widget-prev-sibling (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:widget sibling widget.
Details:
Returns the previous sibling of the widget. This API is primarily meant for widget implementations.
See also:
2025-2-15
Function gtk:widget-first-child (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:widget object.
Details:
Returns the first child of the widget. This API is primarily meant for widget implementations.
See also:
2025-2-15
Function gtk:widget-last-child (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:widget object.
Details:
Returns the last child of the widget. This API is primarily meant for widget implementations.
See also:
2025-2-15
Function gtk:widget-insert-before (widget parent next)
Arguments:
widget -- a gtk:widget object
parent -- a gtk:widget object for the parent widget to insert widget into
next -- a gtk:widget object for the next sibling of widget or nil
Details:
Inserts widget into the child widget list of parent. It will be placed before next, or at the end if next is nil.

After calling this function, the gtk:widget-next-sibling function will return next. If parent is already set as the parent widget of widget, this function can also be used to reorder widget in the child widget list of parent.

This API is primarily meant for widget implementations. If you are just using a widget, you must use its own API for adding children.
See also:
2025-2-15
Function gtk:widget-insert-after (widget parent prev)
Arguments:
widget -- a gtk:widget object
parent -- a gtk:widget object for the parent widget to insert widget into
prev -- a gtk:widget object for the previous sibling of widget or nil
Details:
Inserts widget into the child widget list of parent. It will be placed after prev, or at the beginning if prev is nil.

After calling this function, the gtk:widget-prev-sibling function will return prev. If parent is already set as the parent widget of widget, this function can also be used to reorder widget in the child widget list of parent.

This API is primarily meant for widget implementations. If you are just using a widget, you must use its own API for adding children.
See also:
2025-2-15
Function gtk:widget-should-layout (widget)
Arguments:
widget -- a gtk:widget object
Returns:
True if widget should be included in measureing and allocating.
Details:
Returns whether widget should contribute to the measuring and allocation of its parent. This is false for invisible children, but also for children that have their own surface.
See also:
#2025-2-15
Function gtk:widget-color (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gdk:rgba instance with the color.
Details:
Gets the current foreground color for the CSS style of the widget. This function should only be used in snapshot implementations that need to do custom drawing with the foreground color.

Since 4.10
See also:
2025-2-15
Function gtk:widget-add-css-class (widget class)
Arguments:
widget -- a gtk:widget object
class -- a string for the style class to add, without the leading "." used for notation of style classes
Details:
Adds class to the widget. After calling this function, the style of the widget will match for class, after the CSS matching rules.
Examples:
Get the CSS style classes, add and remove a CSS style class:
(defvar dialog (make-instance 'gtk:about-dialog)) => DIALOG
(gtk:widget-css-classes dialog)
=> ("background" "csd" "aboutdialog")
(gtk:widget-add-css-class dialog "mystyle")
(gtk:widget-css-classes dialog)
=> ("background" "csd" "aboutdialog" "mystyle")
(gtk:widget-remove-css-class dialog "mystyle")
(gtk:widget-css-classes dialog)
=> ("background" "csd" "aboutdialog")    
See also:
2025-2-15
Function gtk:widget-remove-css-class (widget class)
Arguments:
widget -- a gtk:widget object
class -- a string for the style class to remove from widget, without the leading "." used for notation of style classes
Details:
Removes class from widget. After this, the style of the widget will stop matching for class.
See also:
2025-2-15
Function gtk:widget-has-css-class (widget class)
Arguments:
widget -- a gtk:widget object
class -- a string for the style class, without the leading "." used for notation of style classes
Returns:
True if class is currently applied to widget, false otherwise.
Details:
Returns whether class is currently applied to widget.
See also:
2025-2-15
Function gtk:widget-class-css-name (gtype)
Syntax:
(gtk:widget-class-css-name gtype) => name
(setf (gtk:widget-class-css-name gtype) name)
Arguments:
gtype -- a g:type-t type ID
name -- a string for the CSS name
Details:
The gtk:widget-class-css-name function gets the name used by this widget class for matching in CSS code. The (setf gtk:widget-class-css-name) function sets the name. If this function is not called for a given class, the name of the parent class is used.
See also:
2025-2-15
Function gtk:widget-style-context (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:style-context object.
Details:
Returns the style context associated to the widget. The returned object is guaranteed to be the same for the lifetime of the widget.
Warning:
This function is deprecated since 4.10. Style contexts will be removed in GTK 5.
See also:
2025-2-15
Function gtk:widget-add-provider (widget provider &optional priority)
Arguments:
widget -- a gtk:widget object
provider -- a gtk:style-provider object
priority -- an optional unsigned integer for the priority of the style provider
Returns:
The string with an unique identifier for the added provider.
Details:
Adds a style provider to the display of widget to be used in style construction. The style provider is removed from the display when the widget is destroyed. Call the gtk:widget-remove-provider function with the returned unique identifier to remove the provider from the display of the widget.

The lower the priority of the style provider is, the earlier it will be used in the style construction. Typically this will be in the range between the gtk:+priority-fallback+ and gtk:+priority-user+ priorities. The default value is gtk:+priority-application+. See the gtk:style-context-add-provider documentation for more information.
Notes:
This function is a Lisp extension that provides a convenient way to apply a provider to the display of the widget. The style provider is added with the gtk:style-context-add-provider-for-display function. A destroy notify callback function is installed with the g:object-set-data-full function. It removes the style provider with the gtk:style-context-remove-provider-for-display function for the display when the widget is destroyed. Alternativly, you can remove the provider from the display of the widget with the gtk:widget-remove-provider function.
See also:
2025-2-15
Function gtk:widget-remove-provider (widget key)
Arguments:
widget -- a gtk:widget object
key -- a string for the unique identifier for the style provider, this is the return value of the gtk:widget-add-provider function
Details:
Removes a style provider from the display of the widget. The style provider has been added with the gtk:widget-add-provider function.
Notes:
This function calls the destroy notify callback function that has been installed with the gtk:widget-add-provider function. The destroy notify callback function calls the gtk:style-context-remove-provider-for-display function.
See also:
2025-2-15
Function gtk:widget-request-mode (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The gtk:size-request-mode value preferred by widget.
Details:
Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities.
See also:
2025-2-15
Function gtk:widget-preferred-size (widget)
Arguments:
widget -- a gtk:widget object
Returns:
minimum-size -- a gtk:requisition instance with the minimum size, or nil
natural-size -- a gtk:requisition instance with the the natural size, or nil
Details:
Retrieves the minimum and natural size of a widget, taking into account the preference for height-for-width management of the widget.

This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as the gtk:fixed widget.

Use the gtk:widget-measure function if you want to support baseline alignment.
Notes:
Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width.
See also:
#2025-2-15
Function gtk:widget-compute-expand (widget orientation)
Arguments:
widget -- a gtk:widget object
orientation -- a gtk:orientation value with the expand direction
Returns:
The boolean whether the widget tree rooted here should be expanded.
Details:
Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at the hexpand or vexpand properties.

This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded.

The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do.
See also:
2025-2-15
Function gtk:widget-init-template (widget)
Arguments:
widget -- a gtk:widget object
Details:
Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using the gtk:widget-class-set-template function.

It is important to call this function in the instance initializer of a GtkWidget subclass. One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers. Another reason is that when calling the g:object-new function on a widget with composite templates, it is important to build the composite widgets before the construct properties are set. Properties passed to the g:object-new function should take precedence over properties set in the private template XML.
See also:
2024-9-14
Function gtk:widget-dispose-template (widget gtype)
Arguments:
widget -- a gtk:widget object
gtype -- a g:type-t type ID of the widget to finalize the template for
Details:
Clears the template children for the given widget. This function is the opposite of the gtk:widget-init-template function, and it is used to clear all the template children from a widget instance. If you bound a template child to a field in the instance structure, or in the instance private data structure, the field will be set to NULL after this function returns.

You should call this function inside the GObjectClass.dispose() implementation of any widget that called the gtk:widget-init-template function. Typically, you will want to call this function last, right before chaining up to the parent type’s dispose implementation.

Since 4.8
See also:
2024-9-14
Function gtk:widget-class-set-template (gtype template)
Arguments:
gtype -- a g:type-t type ID of the widget class
template -- a string holding the gtk:builder XML
Details:
This should be called at class initialization time to specify the gtk:builder XML to be used to extend a widget. For convenience, the gtk:widget-class-set-template-from-resource function is also provided.

Note that any class that installs templates must call the gtk:widget-init-template function in the instance initializer of the widget.
See also:
2024-9-14
Function gtk:widget-class-set-template-from-resource (gtype name)
Arguments:
gtype -- a g:type-t type ID of the widget class
name -- a string with the name of the resource to load the template from
Details:
A convenience function to call the gtk:widget-class-set-template function.

Note that any class that installs templates must call the gtk:widget-init-template function in the instance initializer of the widget.
See also:
2024-9-14
Function gtk:widget-template-child (widget gtype name)
Arguments:
widget -- a gtk:widget object
gtype -- a g:type-t type ID to get a template child for
name -- a string with the ID of the child defined in the template XML
Returns:
The g:object instance built in the template XML with the ID name.
Details:
Fetch an object build from the template XML for gtype in this widget instance. This will only report children which were previously declared with the gtk:widget-class-bind-template-child function or one of its variants.

This function is only meant to be called for code which is private to the gtype which declared the child and is meant for language bindings which cannot easily make use of the g:object structure offsets.
See also:
2024-9-14
Function gtk:widget-class-bind-template-child (gtype name)
Arguments:
gtype -- a g:type-t type ID of the widget class
name -- a string with the ID of the child defined in the template XML
Details:
Binds a child widget defined in a template to the widget class of type gtype.
See also:
2024-9-14
Function gtk:widget-class-bind-template-callback (gtype name symbol)

No documentation string. Possibly unimplemented or incomplete.

Function gtk:widget-class-set-template-scope (gtype scope)

No documentation string. Possibly unimplemented or incomplete.

Function gtk:widget-observe-children (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The g:list-model object tracking the children of widet.
Details:
Returns a g:list-model object to track the children of widget.

Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned list model. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns.
See also:
#2024-12-9
Function gtk:widget-observe-controllers (widget)
Arguments:
widget -- a gtk:widget object
Returns:
The g:list-model object tracking the controllers of widet.
Details:
Returns a g:list-model object to track the gtk:event-controller objects of widget.

Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned list model. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns.
See also:
#2024-12-9
Function gtk:widget-insert-action-group (widget prefix group)
Arguments:
widget -- a gtk:widget object
prefix -- a string with the prefix for actions in group
group -- a g:action-group instance
Details:
Inserts an action group into widget. Children of widget that implement the gtk:actionable interface can then be associated with actions in group by setting their action-name property to the "prefix.action-name" value.
See also:
2024-5-13
Function gtk:widget-activate-action (widget name)
Arguments:
widget -- a gtk:widget object
name -- a string with the name of the action to activate
Returns:
True if the action was activated, false if the action does not exist.
Details:
Looks up the action in the action groups associated with widget and its ancestors, and activates it.
Notes:
In the Lisp binding the implementation of the parameters for an action is missing.
See also:
2024-11-9

GtkRange

Class gtk:range
Superclasses:
Documented Subclasses:
Direct Slots:
adjustment
The adjustment property of type gtk:adjustment (Read / Write / Construct)
The adjustment that contains the current value of this range object.
fill-level
The fill-level property of type :double (Read / Write)
The fill level, for example, prebuffering of a network stream.
Default value: 1.79769e+308
inverted
The inverted property of type :boolean (Read / Write)
Invert direction slider moves to increase range value.
Default value: false
restrict-to-fill-level
The restrict-to-fill-level property of type :boolean (Read / Write)
Controls whether slider movement is restricted to an upper boundary set by the fill level.
Default value: true
round-digits
The round-digits property of type :int (Read / Write)
The number of digits to round the value to when it changes, or -1. See the "change-value" signal.
Allowed values: >= -1
Default value: -1
show-fill-level
The show-fill-level property of type :boolean (Read / Write)
Controls whether fill level indicator graphics are displayed on the trough.
Default value: false
Slot Access Functions:
Details:
The gtk:range class is the common base class for widgets which visualize an adjustment, for example the gtk:scale widget.

Apart from signals for monitoring the parameters of the adjustment, the gtk:range class provides properties and methods for influencing the sensitivity of the "steppers". It also provides properties and methods for setting a "fill level" on range widgets. See the gtk:range-fill-level function.
Signal Details:
The "adjust-bounds" signal
lambda (range value)    :run-last      
range
The gtk:range widget that received the signal.
value
The double float with the value before we clamp.
Emitted before clamping a value, to give the application a chance to adjust the bounds.
The "change-value" signal
lambda (range scroll value)    :run-last      
range
The gtk:range widget that received the signal.
scroll
The gtk:scroll-type value of scroll action that was performed.
value
The double float resulting from the scroll action.
Returns
True to prevent other handlers from being invoked for the signal, false to propagate the signal further.
The signal is emitted when a scroll action is performed on a range. It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can handle the event itself and return true to prevent further processing. Or, by returning false, it can pass the event to other handlers until the default GTK handler is reached. The value parameter is unrounded. An application that overrides the "change-value" signal is responsible for clamping the value to the desired number of decimal digits. The default GTK handler clamps the value based on "round-digits". It is not possible to use delayed update policies in an overridden "change-value" signal handler.
The "move-slider" signal
lambda (range step)    :action      
range
The gtk:range widget that received the signal.
step
The gtk:scroll-type value how to move the slider.
Virtual function that moves the slider. Used for key bindings.
The "value-changed" signal
lambda (range)    :run-last      
range
The gtk:range widget that received the signal.
Emitted when the range value changes.
See also:
2023-8-24
Accessor gtk:range-adjustment (object)
Syntax:
(gtk:range-adjustment object) => adjustement
(setf (gtk:range-adjustment object) adjustment)
Arguments:
object -- a gtk:range widget
adjustment -- a gtk:adjustment object
Details:
Accessor of the adjustment slot of the gtk:range class. The gtk:range-adjustment function gets the adjustment which is the "model" object for the range. The (setf gtk:range-adjustment) function sets the adjustment.

The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for the gtk:scale widget, and indicates the size of the visible area of the widget being scrolled.
See also:
2023-8-24
Accessor gtk:range-fill-level (object)
Syntax:
(range-fill-level object) => fill-level
(setf (gtk:range-fill-level object) fill-level)
Arguments:
object -- a gtk:range widget
fill-level -- a double float with the new position of the fill level indicator
Details:
Accessor of the fill-level slot of the gtk:range class. The gtk:range-fill-level function gets the current position of the fill level indicator. The (setf gtk:range-fill-level) function sets the position of the fill level indicator.

The "fill level" is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in a streaming media player. In that use case, the value of the range would indicate the current play position, and the fill level would be the position up to which the file/stream has been downloaded.

This amount of prebuffering can be displayed on the trough of the range and is themeable separately from the trough. To enable fill level display, use the gtk:range-show-fill-level function. The range defaults to not showing the fill level.

Additionally, it is possible to restrict the slider position of the range to values which are smaller than the fill level. This is controller by the gtk:range-restrict-to-fill-level function and is by default enabled.
See also:
2023-8-24
Accessor gtk:range-inverted (object)
Syntax:
(gtk:range-inverted object) => setting
(setf (gtk:range-inverted object) setting)
Arguments:
object -- a gtk:range widget
setting -- true to invert the range
Details:
Accessor of the inverted slot of the gtk:range class. The gtk:range-inverted function gets whether the range is inverted.

Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted ranges have higher values at the top or on the right rather than on the bottom or left.
See also:
2023-8-24
Accessor gtk:range-restrict-to-fill-level (object)
Syntax:
(gtk:range-restrict-to-fill-level object) => setting
(setf (gtk:range-restrict-to-fill-level object) setting)
Arguments:
object -- a gtk:range widget
setting -- a boolean whether the fill level restricts slider movement
Details:
Accessor of the restrict-to-fill-level slot of the gtk:range class. The gtk:range-restrict-to-fill-level function gets whether the range is restricted to the fill level. The (setf gtk:range-restrict-to-fill-level) function sets whether the slider is restricted to the fill level. See the gtk:range-fill-level function for a general description of the fill level concept.
See also:
2023-8-24
Accessor gtk:range-round-digits (object)
Syntax:
(gtk:range-round-digits object) => round-digits
(setf (gtk:range-round-digits object) round-digits)
Arguments:
object -- a gtk:range widget
round-digits -- an integer with the precision in digits, or -1
Details:
Accessor of the round-digits slot of the gtk:range class. The gtk:range-round-digits function gets the number of digits to round the value to when it changes. The (setf gtk:range-round-digits) function sets the number of digits to round the value to when it changes. See the "change-value" signal.
See also:
2023-8-24
Accessor gtk:range-show-fill-level (object)
Syntax:
(gtk:range-show-fill-level object) => show-fill-level
(setf (gtk:range-show-fill-level object) show-fill-level)
Arguments:
object -- a gtk:range widget
show-fill-level -- a boolean whether a fill level indicator graphics is shown
Details:
Accessor of the show-fill-level slot of the gtk:range class. The gtk:range-show-fill-level function gets whether the range displays the fill level graphically. The (setf gtk:range-show-fill-level) function sets whether a graphical fill level is show on the trough. See the gtk:range-fill-level function for a general description of the fill level concept.
See also:
2023-8-24
Function gtk:range-value (range)
Syntax:
(gtk:range-value range) => value
(setf (gtk:range-value range) value)
Arguments:
range -- a gtk:range widget
value -- a double float with the value of the range
Details:
Accessor of the value of the range. The gtk:range-value function gets the current value of the range. The (setf gtk:range-value) function sets the current value of the range.

If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The range emits the "value-changed" signal if the value changes.
See also:
2023-8-24
Function gtk:range-set-increments (range step page)
Arguments:
range -- a gtk:range widget
step -- a double float with the step size
page -- a double float with the page size
Details:
Sets the step and page sizes for the range. The step size is used when the user moves the gtk:scale widget via arrow keys. The page size is used for example when moving via Page Up or Page Down keys.
See also:
#2023-8-24
Function gtk:range-set-range (range min max)
Arguments:
range -- a gtk:range widget
min -- a double float with the minimum range value
max -- a double float with the maximum range value
Details:
Sets the allowable values in the range, and clamps the range value to be between min and max. If the range has a non-zero page size, it is clamped between min and (max - page-size).
See also:
#2023-8-24
Function gtk:range-flippable (range)
Syntax:
gtk:range-flippable range) => flippable
(setf (gtk:range-flippable range) flippable)
Arguments:
range -- a gtk:range widget
[flippable -- true to make the range flippable
Details:
Accessor of the flippable property of the range. If a range is flippable, it will switch its direction if it is horizontal and its direction is :rtl. See the gtk:widget-direction function.
See also:
#2023-8-24
Function gtk:range-range-rect (range)
Arguments:
range -- a gtk:range widget
Returns:
The gdk:rectangle instance with the range rectangle.
Details:
This function returns the area that contains the trough of the range and its steppers, in widget window coordinates. This function is useful mainly for gtk:range subclasses.
See also:
#2023-8-24
Function gtk:range-slider-range (range)
Arguments:
range -- a gtk:range widget
Returns:
start -- an integer with the start of the slider, or nil
end -- an integer with the end of the slider, or nil
Details:
This function returns sliders range along the long dimension, in widget window coordinates. This function is useful mainly for gtk:range subclasses.
See also:
#2023-8-24
Function gtk:range-slider-size-fixed (range)
Syntax:
(gtk:range-slider-size-fixed range) => fixed
(setf (gtk:range-slider-size-fixed range) fixed)
Arguments:
range -- a gtk:range widget
fixed -- true to make the slider size constant
Details:
Whether the slider of the range has a fixed size. Sets whether the slider of the range has a fixed size, or a size that depends on its page size of the adjustment.

This function is useful mainly for gtk:range subclasses.
See also:
#2023-8-24

Printing

GtkPrintOperationPreview

Interface gtk:print-operation-preview
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:print-operation-preview interface is implemented by the gtk:print-operation class.

By default the gtk:print-operation object uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The gtk:print-operation-preview-render-page, gtk:print-operation-preview-end-preview and gtk:print-operation-preview-is-selected functions are useful when implementing a print preview.
Signal Details:
The "got-page-size" signal
lambda (preview context page-setup)    :run-last      
preview
The gtk:print-operation-preview object on which the signal is emitted.
context
The current gtk:print-context object.
page-setup
The gtk:page-setup object for the current page.
The signal is emitted once for each page that gets rendered to the preview. A handler for this signal should update the context according to the page-setup argument and set up a suitable Cairo context, using the gtk:print-context-set-cairo-context function.
The "ready" signal
lambda (preview context)    :run-last      
preview
The gtk:print-operation-preview object on which the signal is emitted.
context
The current gtk:print-context object.
The signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks.
See also:
2023-8-28
Function gtk:print-operation-preview-end-preview (preview)
Arguments:
preview -- a gtk:print-operation-preview object
Details:
Ends a preview. This function must be called to finish a custom print preview.
See also:
#2023-8-28
Function gtk:print-operation-preview-is-selected (preview page-nr)
Arguments:
preview -- a gtk:print-operation-preview object
page-nr -- a page number
Returns:
True if the page has been selected for printing.
Details:
Returns whether the given page is included in the set of pages that have been selected for printing.
See also:
#2023-8-28
Function gtk:print-operation-preview-render-page (preview page-nr)
Arguments:
preview -- a gtk:print-operation-preview object
page-nr -- the number of the page to render
Details:
Renders a page to the preview, using the print context that was passed to the "preview" handler together with preview. A custom print preview should use this function in its "expose" handler to render the currently selected page. Note that this function requires a suitable Cairo context to be associated with the print context.
See also:
#2023-8-28

GtkPrintOperation

GEnum gtk:print-status
Declaration:
(gobject:define-genum "GtkPrintStatus" print-status
  (:export t
   :type-initializer "gtk_print_status_get_type")
  (:initial 0)
  (:preparing 1)
  (:generating-data 2)
  (:sending-data 3)
  (:pending 4)
  (:pending-issue 5)
  (:printing 6)
  (:finished 7)
  (:finished-aborted 8))  
Values:
:initial
The printing has not started yet. This status is set initially, and while the print dialog is shown.
:preparing
This status is set while the "begin-print" signal is emitted and during pagination.
:generating-data
This status is set while the pages are being rendered.
:sending-data
The print job is being sent off to the printer.
:pending
The print job has been sent to the printer, but is not printed for some reason, for example, the printer may be stopped.
:pending-issue
Some problem has occurred during printing, for example a paper jam.
:printing
The printer is processing the print job.
:finished
The printing has been completed successfully.
:finished-aborted
The printing has been aborted.
Details:
The status gives a rough indication of the completion of a running print operation.
See also:
2023-8-28
GEnum gtk:print-operation-action
Declaration:
(gobject:define-genum "GtkPrintOperationAction" print-operation-action
  (:export t
   :type-initializer "gtk_print_operation_action_get_type")
  (:print-dialog 0)
  (:print 1)
  (:preview 2)
  (:export 3))  
Values:
:print-dialog
Show the print dialog.
:print
Start to print without showing the print dialog, based on the current print settings.
:preview
Show the print preview.
:export
Export to a file. This requires the export-filename property of the gtk:print-operation object to be set.
Details:
The action parameter to the gtk:print-operation-run function determines what action the print operation should perform.
See also:
2023-8-28
GEnum gtk:print-operation-result
Declaration:
(gobject:define-genum "GtkPrintOperationResult" print-operation-result
  (:export t
   :type-initializer "gtk_print_operation_result_get_type")
  (:error 0)
  (:apply 1)
  (:cancel 2)
  (:in-progress 3))  
Values:
:error
An error has occured.
:apply
The print settings should be stored.
:cancel
The print operation has been canceled, the print settings should not be stored.
:in-progress
The print operation is not complete yet. This value will only be returned when running asynchronously.
Details:
A value of this type is returned by the gtk:print-operation-run function.
See also:
2023-8-28
Class gtk:print-operation
Superclasses:
gtk:print-operation-preview, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
allow-async
The allow-async property of type :boolean (Read / Write)
Determines whether the print operation may run asynchronously or not. Some systems do not support asynchronous printing, but those that do will return :in-progress as the status, and emit the "done" signal when the operation is actually done. The Windows port does not support asynchronous operation at all, this is unlikely to change. On other platforms, all actions except for :export support asynchronous operation.
Default value: false
current-page
The current-page property of type :int (Read / Write)
The current page in the document. If this is set before the function gtk:print-operation-run, the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents.
Allowed values: >= -1
Default value: -1
custom-tab-label
The custom-tab-label property of type :string (Read / Write)
Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is nil, GTK uses a default label.
Default value: nil
default-page-setup
The default-page-setup property of type gtk:page-setup (Read / Write)
The page setup used by default. This page setup will be used by the gtk:print-operation-run function, but it can be overridden on a per-page basis by connecting to the "request-page-setup" signal.
embed-page-setup
The embed-page-setup property of type :boolean (Read / Write)
If true, the page size combo box and the orientation combo box are embedded into the page setup page.
Default value: false
export-filename
The export-filename property of type :string (Read / Write)
The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. The intended use of this property is for implementing "Export to PDF" actions. "Print to PDF" support is independent of this and is done by letting the user pick the "Print to PDF" item from the list of printers in the print dialog.
Default value: nil
has-selection
The has-selection property of type :boolean (Read / Write)
Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive.
Default value: false
job-name
The job-name property of type :string (Read / Write)
A string used to identify the job, for example, in monitoring applications like eggcups. If you do not set a job name, GTK picks a default one by numbering successive print jobs.
Default value: ""
n-pages
The n-pages property of type :int (Read / Write)
The number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a "begin-print" signal handler. Note that the page numbers passed to the "request-page-setup" and "draw-page" signal handlers are 0-based, that is, if the user chooses to print all pages, the last "draw-page" signal will be for page n-pages - 1
Allowed values: >= -1
Default value: -1
n-pages-to-print
The n-pages-to-print property of type :int (Read)
The number of pages that will be printed. Note that this value is set during the print preparation :preparing phase, so this value should never be get before the data generation :generating-data phase. You can connect to the "status-changed" signal and call the gtk:print-operation-n-pages-to-print function when the print status is in the :generating-data phase. This is typically used to track the progress of print operation.
Allowed values: >= -1
Default value: -1
print-settings
The print-settings property of type gtk:print-settings (Read / Write)
The print settings used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see the gtk:print-operation-run function.
show-progress
The show-progress property of type :boolean (Read / Write)
Determines whether to show a progress dialog during the print operation.
Default value: false
status
The status property of type gtk:print-status (Read)
The status of the print operation.
Default value: :initial
status-string
The status-string property of type :string (Read)
A string representation of the status of the print operation. The string is translated and suitable for displaying the print status, for example in a gtk:statusbar widget. See the status property for a status value that is suitable for programmatic use.
Default value: ""
support-selection
The support-selection property of type :boolean (Read / Write)
If true, the print operation will support print of selection. This allows the print dialog to show a "Selection" button.
Default value: false
track-print-status
The track-print-status property of type :boolean (Read / Write)
If true, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like "out of paper" issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed.
Default value: false
unit
The unit property of type gtk:unit (Read / Write)
The transformation for the Cairo context obtained from the gtk:print-context object is set up in such a way that distances are measured in units of a value of the gtk:unit enumeration.
Default value: :pixel
use-full-page
The use-full-page property of type :boolean (Read / Write)
If true, the transformation for the Cairo context obtained from the gtk:print-context object puts the origin at the top left corner of the page, which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet. Otherwise, the origin is at the top left corner of the imageable area, that is inside the margins.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:print-operation object is the high-level, portable printing API. It looks a bit different than other GTK dialogs such as the gtk:file-chooser widget, since some platforms do not expose enough infrastructure to implement a good print dialog. On such platforms, the gtk:print-operation object uses the native print dialog. On platforms which do not provide a native print dialog, GTK uses its own, see the gtk:print-unix-dialog implementation.

The typical way to use the high-level printing API is to create a gtk:print-operation object with the gtk:print-operation-new function when the user selects to print. Then you set some properties on it, for example the page size, any gtk:print-settings settings from previous print operations, the number of pages, the current page, and so on.

Then you start the print operation by calling the gtk:print-operation-run function. It will then show a dialog, let the user select a printer and options. When the user finished the dialog various signals will be emitted on the gtk:print-operation object, the main one being the "draw-page" signal, which you are supposed to catch and render the page on the provided the gtk:print-context object using Cairo.

By default the gtk:print-operation object uses an external application to do print preview. To implement a custom print preview, an application must connect to the "preview" signal. The gtk:print-operation-preview-render-page, gtk:print-operation-preview-end-preview and gtk:print-operation-preview-is-selected functions are useful when implementing a print preview.
Examples:
The high-level printing API.
(defvar *print-settings* nil)

(defun do-print-operation (window) (let ((response nil) (print (gtk:print-operation-new))) ;; Connect signal handlers for the print operation (g:signal-connect print "draw-page" #'draw-page) (g:signal-connect print "begin-print" #'begin-print) ;; Restore the print settings (when *print-settings* (setf (gtk:print-operation-print-settings print) *print-settings*)) ;; Perform the print operation (setf response (gtk:print-operation-run print :print-dialog window)) ;; Check the response and save the print settings (when (eq :apply response) (setf *print-settings* (gtk:print-operation-print-settings print)))))
Signal Details:
The "begin-print" signal
lambda (operation context)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
context
The gtk:print-context object for the current operation.
Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for the "begin-print" signal is to use the parameters from the gtk:print-context object and paginate the document accordingly, and then set the number of pages with the gtk:print-operation-n-pages function.
The "create-custom-widget" signal
lambda (operation)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
Returns
A gtk:widget custom widget that gets embedded in the print dialog, or nil.
Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it. The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the "custom-widget-apply" signal is emitted on the operation. Then you can read out any information you need from the widgets.
The "custom-widget-apply" signal
lambda (operation widget)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
widget
The gtk:widget custom widget added in a "create-custom-widget" signal handler.
Emitted right before the "begin-print" signal if you added a custom widget in the "create-custom-widget" signal handler. When you get this signal you should read the information from the custom widgets, as the widgets are not guaraneed to be around at a later time.
The "done" signal
lambda (operation result)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
result
The result of type gtk:print-operation-result of the print operation.
Emitted when the print operation run has finished doing everything required for printing. result gives you information about what happened during the run. If result is :error then you can call the gtk_print_operation_get_error () function for more information. If you enabled print status tracking then the gtk:print-operation-is-finished function may still return false after the "done" signal was emitted.
The "draw-page" signal
lambda (operation context page-nr)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
context
The gtk:print-context object for the current operation.
page-nr
The 0-based number of the currently printed page.
Emitted for every page that is printed. The signal handler must render the page-nr's page onto the Cairo context obtained from context using the gtk:print-context-cairo-context function. Use the gtk:print-operation-use-full-page and gtk:print-operation-unit functions before starting the print operation to set up the transformation of the Cairo context according to your needs.
(defun draw-page (operation context page-nr)
  (declare (ignore operation page-nr))
  (let ((text-height 0)
        (cr (gtk:print-context-cairo-context context))
        (width (floor (gtk:print-context-get-width context)))
        (layout (gtk:print-context-create-pango-layout context)))
    ;; Print a grey colored header
    (cairo-rectangle cr 0 0 width *header-height*)
    (cairo-set-source-rgb cr 0.9 0.9 0.9)
    (cairo-fill cr)
    ;; Set the font and text to print
    (setf (pango:layout-font-description layout)
          (pango:font-description-from-string "sans 14"))
    (setf (pango:layout-text layout) "Title")
    (setf (pango:layout-width layout) (* width pango:+scale+))
    (setf (pango:layout-alignment layout) :center)
    ;; Get the height of the text
    (multiple-value-bind (width height)
        (pango:layout-size layout)
      (setf text-height (/ height pango:+scale+)))
    ;; Set color to black and center the text in header
    (cairo-set-source-rgb cr 0.0 0.0 0.0)
    (cairo-move-to cr 0 (floor (/ (- *header-height* text-height) 2)))
    (pango:cairo-show-layout cr layout)))      
The "end-print" signal
lambda (operation context)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
context
The gtk:print-context object for the current operation.
Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the "begin-print" signal handler.
The "paginate" signal
lambda (operation context)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
context
The gtk:print-context object for the current operation.
Emitted after the "begin-print" signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns true. The "paginate" signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using the gtk:print-operation-n-pages function, and return true if the document has been completely paginated. If you do not need to do pagination in chunks, you can simply do it all in the "begin-print" signal handler, and set the number of pages from there.
The "preview" signal
lambda (operation preview context parent)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
preview
The gtk:print-preview-operation object for the current operation.
context
The gtk:print-context object that will be used.
parent
The gtk:window widget to use as window parent, or nil.
Returns
True if the listener wants to take over control of the preview.
Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. To implement a custom print preview, an application must return true from its handler for this signal. In order to use the provided context for the preview implementation, it must be given a suitable Cairo context with the gtk:print-context-set-cairo-context function. The custom preview implementation can use the gtk:print-operation-preview-is-selected and gtk:print-operation-preview-render-page functions to find pages which are selected for print and render them. The preview must be finished by calling the gtk:print-operation-preview-end-preview function, typically in response to the user clicking a Close button.
The "request-page-setup" signal
lambda (operation context page-nr setup)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
context
The gtk:print-context object for the current operation.
page-nr
The 0-based number of the currently printed page.
setup
The gtk:page-setup object.
Emitted once for every page that is printed, to give the application a chance to modify the page setup. Any changes done to the page setup will be in force only for printing this page.
The "status-changed" signal
lambda (operation)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
Emitted at between the various phases of the print operation. See the gtk:print-status enumeration for the phases that are being discriminated. Use the gtk:print-operation-status function to find out the current status.
The "update-custom-widget" signal
lambda (operation widget setup settings)    :run-last      
operation
The gtk:print-operation object on which the signal was emitted.
widget
The gtk:widget custom widget added in the "create-custom-widget" signal handler.
setup
Actual gtk:page-setup object.
settings
Actual gtk:print-settings object.
Emitted after change of the selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change.
See also:
2023-8-28
Accessor gtk:print-operation-allow-async (object)
Syntax:
(gtk:print-operation-allow-async object) => alloc-async
(setf (gtk:print-operation-allow-aysnc object) alloc-async)
Arguments:
object -- a gtk:print-operation object
allow-async -- true to allow asynchronous operation
Details:
Accessor of the allow-async slot of the gtk:print-operation class. The (setf gtk:print-operation-allow-async) function sets whether the gtk:print-operation-run function may return before the print operation is completed.

Note that some platforms may not allow asynchronous operation.
See also:
2023-8-28
Accessor gtk:print-operation-current-page (object)
Syntax:
(gtk:print-operation-current-page object) => current-page
(setf (gtk:print-operation-current-page object) current-page)
Arguments:
object -- a gtk:print-operation object
current-page -- the current page, 0-based
Details:
Accessor of the current-page slot of the gtk:print-operation class. The (setf gtk:print-operation-current-page) function sets the current page. If this is called before the gtk:print-operation-run function, the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents.
See also:
2023-8-28
Accessor gtk:print-operation-custom-tab-label (object)
Syntax:
(gtk:print-operation-tab-label object) => label
(setf (gtk:print-operation-tab-label object) label)
Arguments:
object -- a gtk:print-operation object
label -- a string with the label to use, or nil to use the default label
Details:
Accessor of the custom-tab-label slot of the gtk:print-operation class. The (setf gtk:print-operation-custom-tab-label) function sets the label for the tab holding custom widgets.
See also:
2023-8-28
Accessor gtk:print-operation-default-page-setup (object)
Syntax:
(gtk:print-operation-default-page-setup object) => page-setup
(setf (gtk:print-operation-default-page-setup object) page-setup)
Arguments:
object -- a gtk:print-operation object
page-setup -- a gtk:page-setup, or nil
Details:
Accessor of the default-page-setup slot of the gtk:print-operation class. The gtk:print-operation-default-page-setup function returns the default page setup. The (setf gtk:print-operation-current-page) function makes page-setup the default page setup for the print operation.

This page setup will be used by the gtk:print-operation-run function, but it can be overridden on a per-page basis by connecting to the "request-page-setup" signal.
See also:
2023-8-28
Accessor gtk:print-operation-embed-page-setup (object)
Syntax:
(gtk:print-operation-embed-page-setup object) => embed
(setf (gtk:print-operation-embed-page-setup object) embed)
Arguments:
object -- a gtk:print-operation object
embed -- true to embed page setup selection in the print dialog
Details:
Accessor of the embed-page-setup slot of the gtk:print-operation class. The gtk:print-operation-embed-page-setup function returns whether page setup selection combos are embedded. The (setf gtk:print-operation-embed-page-setup) function embed page size combo box and orientation combo box into page setup page.

Selected page setup is stored as default page setup in the gtk:print-operation object.
See also:
2023-8-28
Accessor gtk:print-operation-export-filename (object)
Syntax:
(gtk:print-operation-export-filename object) => filename
(setf (gtk:print-operation-export-filename object) filename)
Arguments:
object -- a gtk:print-operation object
filename -- a string with the filename for the exported file
Details:
Accessor of the export-filename slot of the gtk:print-operation class. The (setf gtk:print-operation-export-filename) function sets up the gtk:print-operation object to generate a file instead of showing the print dialog.

The indended use of this function is for implementing "Export to PDF" actions. Currently, PDF is the only supported format.

"Print to PDF" support is independent of this and is done by letting the user pick the "Print to PDF" item from the list of printers in the print dialog.
See also:
2023-8-28
Accessor gtk:print-operation-has-selection (object)
Syntax:
(gtk:print-operation-has-selection object object) => has-selection
(setf (gtk:print-operation-has-selection object) has-selection)
Arguments:
object -- a gtk:print-operation object
has-selection -- true indicates that a selection exists
Details:
Accessor of the has-selection slot of the gtk:print-operation class. The gtk:print-operation-has-selection function returns whether there is a selection. The (setf gtk:print-operation-has-selection) function sets whether there is a selection to print.

The application has to set the number of pages to which the selection will draw by the gtk:print-operation-n-pages function in a callback of the "begin-print" signal.
See also:
2023-8-28
Accessor gtk:print-operation-job-name (object)
Syntax:
(gtk:print-operation-job-name object) => job-name
(setf (gtk:print-operation-job-name object) job-name)
Arguments:
object -- a gtk:print-operation-job-name object
job-name -- a string that identifies the print job
Details:
Accessor of the job-name slot of the gtk:print-operation class. The gtk:print-operation-job-name function sets the name of the print job.

The name is used to identify the job, for example, in monitoring applications like eggcups.

If you do not set a job name, GTK picks a default one by numbering successive print jobs.
See also:
2023-8-28
Accessor gtk:print-operation-n-pages (object)
Syntax:
(gtk:print-operation-n-pages object) => npages
(setf (gtk:print-operation-n-pages object) npages)
Arguments:
object -- a gtk:print-operation object
npages -- an integer with the number of pages
Details:
Accessor of the n-pages slot of the gtk:print-operation class. The gtk:print-operation-n-pages function gets the number of pages in the document. The (setf gtk:print-operation-n-pages) function sets the number of pages.

This must be set to a positive number before the rendering starts. It may be set in a "begin-print" signal handler. Note that the page numbers passed to the "request-page-setup" and "draw-page" signal handlers are 0-based, that is, if the user chooses to print all pages, the last "draw-page" signal will be for page npages - 1.
See also:
2024-2-16
Accessor gtk:print-operation-n-pages-to-print (object)
Syntax:
(gtk:print-operation-n-pages-to-print object) => npages
Arguments:
object -- a gtk:print-operation object
npages -- an integer with the number of pages to print
Details:
Accessor of the n-pages-to-print slot of the gtk:print-operation class. The gtk:print-operation-n-pages-to-print function returns the number of pages that will be printed.

Note that this value is set during the print preparation :preparing phase, so this function should never be called before the data generation :generating-data phase. You can connect to the "status-changed" signal and call the gtk:print-operation-n-pages-to-print function when the print status is in the :generating-data phase. This is typically used to track the progress of print operation.
See also:
2024-2-16
Accessor gtk:print-operation-print-settings (object)
Syntax:
(gtk:print-operation-print-settings object) => settings
(setf (gtk:print-operation-print-settings object) settings)
Arguments:
object -- a gtk:print-operation object
settings -- a gtk:print-settings object
Details:
Accessor of the print-settings slot of the gtk:print-operation class. The gtk:print-operation-print-settings function returns the current print settings. The (setf gtk:print-operation-print-settings) function sets the print settings for the print operation. This is typically used to re-establish print settings from a previous print operation.

Note that the return value is nil until either the gtk:print-operation-print-settings function or the gtk:print-operation-run function have been called.
See also:
2023-8-28
Accessor gtk:print-operation-show-progress (object)
Syntax:
(gtk:print-operation-show-progress object) => show-progress
(setf (gtk:print-operation-show-progress object) show-progress)
Arguments:
object -- a gtk:print-operation object
show-progress -- true to show a progress dialog
Details:
Accessor of the show-progress of the gtk:print-operation class. If show-progress is true, the print operation will show a progress dialog during the print operation.
See also:
2023-8-28
Accessor gtk:print-operation-status (object)
Syntax:
(gtk:print-operation-status object) => status
Arguments:
object -- a gtk:print-operation object
status -- the status of type gtk:print-status of the print operation
Details:
Accessor of the status slot of the gtk:print-operation class. The gtk:print-operation-status function returns the status of the print operation.

Also see the gtk:print-operation-status-string function.
See also:
2023-8-28
Accessor gtk:print-operation-status-string (object)
Syntax:
(gtk:print-operation-status-string object) => status-string
Arguments:
object -- a gtk:print-operation object
status-string -- a string representation of the status of the print operation
Details:
Accessor of the status-string slot of the gtk:print-operation class. The gtk:print-operation-status-string function returns a string representation of the status of the print operation.

The string is translated and suitable for displaying the print status, for example in a gtk:statusbar widget.

Use the gtk:print-operation-status function to obtain a status value that is suitable for programmatic use.
See also:
2023-8-28
Accessor gtk:print-operation-support-selection (object)
Syntax:
(gtk:print-operation-status-support-selection object) => setting
(setf (gtk:print-operation-support-selection object) setting)
Arguments:
object -- a gtk:print-operation object
setting -- true to support selection
Details:
Accessor of the support-selection slot of the gtk:print-operation class. The gtk:print-operation-support-selection function returns whether the application supports print of selection. The (setf gtk:print-operation-support-selection) function sets whether selection is supported by the print operation.
See also:
2023-8-28
Accessor gtk:print-operation-track-print-status (object)
Syntax:
(gtk:print-operation-track-print-status object) => track-status
(setf (gtk:print-operation-track-print-status object) track-status)
Arguments:
object -- a gtk:print-operation object
track-status -- true to track status after printing
Details:
Accessor of the track-print-status slot of the gtk:print-operation class. If track-status is true, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like "out of paper" issues, and when the print job actually reaches the printer.

This function is often implemented using some form of polling, so it should not be enabled unless needed.
See also:
2023-8-28
Accessor gtk:print-operation-unit (object)
Syntax:
(gtk:print-operation-unit object) => unit
(setf (gtk:print-operation-unit object) unit)
Arguments:
object -- a gtk:print-operation object
unit -- the unit to use
Details:
Accessor of the unit slot of the gtk:print-operation class. The (setf gtk:print-operation-unit) function sets up the transformation for the Cairo context obtained from the gtk:print-context object in such a way that distances are measured in units of a value of the gtk:unit enumeration.
See also:
2023-8-28
Accessor gtk:print-operation-use-full-page (object)
Syntax:
(gtk:print-operation-use-full-page object) => full-page
(setf (gtk:print-operation-use-full-page object) full-page)
Arguments:
object -- a gtk:print-operation object
full-page -- true to set up the gtk:print-context object for the full page
Details:
Accessor of the use-full-page of the gtk:print-operation class. If full-page is true, the transformation for the Cairo context obtained from the gtk:print-context object puts the origin at the top left corner of the page, which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet. Otherwise, the origin is at the top left corner of the imageable area, that is inside the margins.
See also:
2023-8-28
Function gtk:print-operation-new ()
Returns:
The new gtk:print-operation object.
Details:
Creates a new gtk:print-operation object.
See also:
2023-8-28
Function gtk:print-operation-run (operation action parent)
Arguments:
operation -- a gtk:print-operation object
action -- a gtk:print-operation-action value for the action to start
parent -- a transient parent of the dialog
Returns:
The result of the print operation. A return value of :apply indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with the gtk:print-operation-print-settings function and store them for reuse with the next print operation. A value of :in-progress means the operation is running asynchronously, and will emit the "done" signal when done.
Details:
Runs the print operation, by first letting the user modify print settings in the print dialog, and then print the document.

Normally that this function does not return until the rendering of all pages is complete. You can connect to the "status-changed" signal on the print operation to obtain some information about the progress of the print operation. Furthermore, it may use a recursive main loop to show the print dialog.

If you call the gtk:print-operation-allow-async function the operation will run asynchronously if this is supported on the platform. The "done" signal will be emitted with the result of the operation when the it is done, that is, when the dialog is canceled, or when the print succeeds or fails.

Note that the gtk:print-operation-run function can only be called once on a given gtk:print-operation.
Examples:
(defun do-print-operation (window)
  (let ((response nil)
        (print (gtk:print-operation-new)))
    ;; Connect signal handlers for the print operation
    (g:signal-connect print "draw-page" #'draw-page)
    (g:signal-connect print "begin-print" #'begin-print)
    ;; Restore the print settings
    (when *print-settings*
      (setf (gtk:print-operation-print-settings print) *print-settings*))
    ;; Restore the page setup
    (when *page-setup*
      (setf (gtk:print-operation-page-setup print) *page-setup*))
    ;; Perform the print operation
    (setf response (gtk:print-operation-run print :print-dialog window))
    ;; Check the response and save the print settings
    (when (eq :apply response)
      (setf *print-settings* (gtk:print-operation-print-settings print)))))    
See also:
#2024-11-21
Function gtk:print-operation-cancel (operation)
Arguments:
operation -- a gtk:print-operation object
Details:
Cancels a running print operation. This function may be called from a "begin-print", "paginate" or "draw-page" signal handler to stop the currently running print operation.
See also:
#2023-8-28
Function gtk:print-operation-draw-page-finish (operation)
Arguments:
operation -- a gtk:print-operation object
Details:
Signalize that drawing of the particular page is complete. The function is called after completion of page drawing, for example drawing in another thread. If the gtk:print-operation-set-defer-drawing function was called before, then this function has to be called by the application. In another case it is called by the library itself. gtk:print-operation-set-defer-drawing
See also:
#2023-8-28
Function gtk:print-operation-set-defer-drawing (operation)
Arguments:
operation -- a gtk:print-operation object
Details:
Sets up the gtk:print-operation object to wait for calling of the gtk:print-operation-draw-page-finish function from the application. It can be used for drawing page in another thread.

This function must be called in the callback of a "draw-page" signal.
See also:
#2023-8-28
Function gtk:print-operation-is-finished (operation)
Arguments:
operation -- a gtk:print-operation object
Returns:
True, if the print operation is finished.
Details:
A convenience function to find out if the print operation is finished, either successfully :finished or unsuccessfully :finished-aborted.
Notes:
When you enable print status tracking the print operation can be in a non-finished state even after the "done" signal has been called, as the operation status then tracks the print job status on the printer.
See also:
#2023-8-28
Function gtk:print-run-page-setup-dialog (parent page-setup settings)
Arguments:
parent -- transient parent
page-setup -- an existing gtk:page-setup object
settings -- a gtk:print-settings object
Returns:
The new gtk:page-setup object.
Details:
Runs a page setup dialog, letting the user modify the values from page-setup. If the user cancels the dialog, the returned gtk:page-setup object is identical to the passed in page-setup, otherwise it contains the modifications done in the dialog.

Note that this function may use a recursive main loop to show the page setup dialog. See the gtk_print_run_page_setup_dialog_async() function if this is a problem.
See also:
#2023-8-28
Callback gtk:page-setup-done-func
Syntax:
lambda (pagesetup)
Arguments:
pagesetup -- a gtk:page-setup object
Details:
The type of function that is passed to the gtk:print-run-page-setup-dialog-async function. This function will be called when the page setup dialog is dismissed.
See also:
#2024-5-3
Function gtk:print-run-page-setup-dialog-async (parent page-setup settings done-cb)
Arguments:
parent -- a gtk:window transient parent, or nil
page-setup -- an existing gtk:page-setup, or nil
settings -- a gtk:print-settings object
done-cb -- a function to call when the user saves the modified page setup
Details:
Runs a page setup dialog, letting the user modify the values from page-setup. In contrast to the gtk:print-run-page-setup-dialog function, this function returns after showing the page setup dialog on platforms that support this, and calls done-cb from a signal handler for the "response" signal of the dialog.
See also:
#2023-8-28

GtkPrintContext

Class gtk:print-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:print-context object encapsulates context information that is required when drawing pages for printing, such as the Cairo context and important parameters like page size and resolution. It also lets you create pango:layout and pango:context objects that match the font metrics of the Cairo surface.

The gtk:print-context object gets passed to the "begin-print", "end-print", "request-page-setup" and "draw-page" signal handlers on the print operation.
Examples:
Using the gtk:print-context object in a draw-page callback function.
(defun draw-page (operation context pagenr)
  (declare (ignore operation pagenr))
  (let ((cr (gtk:print-context-cairo-context context))
        (layout (gtk:print-context-create-pango-layout context)))
    ;; Draw a red rectangle, as wide as the paper (inside the margins)
    (cairo:set-source-rgb cr 1.0 0 0)
    (cairo:rectangle cr 0 0 (gtk:print-context-width context) 50)
    (cairo:fill cr)
    ;; Draw some lines
    (cairo:move-to cr 20 10)
    (cairo:line-to cr 40 20)
    (cairo:arc cr 60 60 20 0 3.14)
    (cairo:line-to cr 80 20)
    (cairo:set-source-rgb cr 0 0 0)
    (cairo:set-line-width cr 5)
    (cairo:set-line-cap cr :round)
    (cairo:set-line-join cr :round)
    (cairo:stroke cr)
    ;; Draw some text
    (setf (pango:layout-text layout) "Hello World! Printing is easy")
    (setf (pango:layout-font-description layout)
          (pango:font-description-from-string "sans 28"))
    (cairo:move-to cr 30 20)
    (pango:cairo-layout-path cr layout)
    ;; Font Outline
    (cairo:set-source-rgb cr 0.93 1.0 0.47)
    (cairo:set-line-width cr 0.5)
    (cairo:stroke-preserve cr)
    ;; Font Fill
    (cairo:set-source-rgb cr 0 0.0 1.0)
    (cairo:fill cr)))    
See also:
2024-2-16
Function gtk:print-context-cairo-context (context)
Arguments:
context -- a gtk:print-context object
Returns:
The cairo:context-t instance with the Cairo context of context.
Details:
Obtains the Cairo context that is associated with the print context.
See also:
#2024-2-16
Function gtk:print-context-set-cairo-context (context cr xdpi ydpi)
Arguments:
context -- a gtk:print-context object
cr -- a cairo:context-t instance with the Cairo context
xdpi -- a number coerced to a double float with the horizontal resolution to use with cr
ydpi -- a number coerced to a double float with the vertical resolution to use with cr
Details:
Sets a new Cairo context on a print context. This function is intended to be used when implementing an internal print preview, it is not needed for printing, since GTK itself creates a suitable Cairo context in that case.
See also:
#2024-2-16
Function gtk:print-context-page-setup (context)
Arguments:
context -- a gtk:print-context object
Returns:
The gtk:page-setup object with the page setup of the print context.
Details:
Obtains the page setup that determines the page dimensions of the print context.
See also:
#2024-2-16
Function gtk:print-context-width (context)
Arguments:
context -- a gtk:print-context object
Returns:
The double float with the width of context.
Details:
Obtains the width of the print context, in pixels.
See also:
2024-2-16
Function gtk:print-context-height (context)
Arguments:
context -- a gtk:print-context object
Returns:
The double float with the height of context.
Details:
Obtains the height of the print context, in pixels.
See also:
2024-2-16
Function gtk:print-context-dpi-x (context)
Arguments:
context -- a gtk:print-context object
Returns:
The double float with the horizontal resolution of context.
Details:
Obtains the horizontal resolution of the print context, in dots per inch.
See also:
#2024-2-16
Function gtk:print-context-dpi-y (context)
Arguments:
context -- a gtk:print-context object
Returns:
The double float with the vertical resolution of context.
Details:
Obtains the vertical resolution of the print context, in dots per inch.
See also:
#2024-2-16
Function gtk:print-context-pango-fontmap (context)
Arguments:
context -- a gtk:print-context object
Returns:
The pango:font-map object with the font map of context.
Details:
Returns a font map that is suitable for use with the print context.
See also:
#2024-2-16
Function gtk:print-context-create-pango-context (context)
Arguments:
context -- a gtk:print-context object
Returns:
The new pango:context object with the Pango context for context.
Details:
Creates a new Pango context that can be used with the print context.
See also:
#2024-2-16
Function gtk:print-context-create-pango-layout (context)
Arguments:
context -- a gtk:print-context object
Returns:
The new pango:layout object for context.
Details:
Creates a new Pango layout that is suitable for use with the print context.
See also:
2024-2-16
Function gtk:print-context-hard-margins (context)
Arguments:
context -- a gtk:print-context object
Returns:
top -- an integer with the top hardware printer margin
bottom -- an integer with the bottom hardware printer margin
left -- an integer with the left hardware printer margin
right -- an integer with the right hardware printer margin
Details:
Obtains the hardware printer margins of the print context, in units.
See also:
#2024-2-16

GtkPaperSize

GEnum gtk:unit
Declaration:
(gobject:define-genum "GtkUnit" unit
  (:export t
   :type-initializer "gtk_unit_get_type")
  (:none 0)
  (:points 1)
  (:inch 2)
  (:mm 3))  
Values:
:none
No units.
:points
Dimensions in points.
:inch
Dimensions in inches.
:mm
Dimensions in millimeters.
Details:
Enumeration for dimensions of paper sizes.
See also:
2025-1-6
GBoxed gtk:paper-size
Declaration:
(glib:define-gboxed-opaque paper-size "GtkPaperSize"
  :type-initializer "gtk_paper_size_get_type"
  :alloc (cffi:foreign-funcall "gtk_paper_size_new"
                               :pointer (cffi:null-pointer)
                               :pointer))  
Returned by:
Details:
The gtk:paper-size structure handles paper sizes. It uses the standard called "PWG 5101.1-2002 PWG: Standard for Media Standardized Names" to name the paper sizes and to get the data for the page sizes. In addition to standard paper sizes, the gtk:paper-size structure allows to construct custom paper sizes with arbitrary dimensions.

The gtk:paper-size instance stores not only the dimensions (width and height) of a paper size and its name, it also provides default print margins.
See also:
2025-1-6
Function gtk:paper-size-new (&optional name)
Arguments:
name -- a string for the paper size name, or nil
Returns:
The new gtk:paper-size instance.
Details:
Creates a new gtk:paper-size instance by parsing a PWG 5101.1-2002 paper name. If the name argument is nil, the default paper size is returned, see the gtk:paper-size-default function.
See also:
2025-1-6
Function gtk:paper-size-new-from-ppd (name &optional displayname width height)
Arguments:
name -- a string for the PPD paper name
displayname -- a string for the corresponding human readable name
width -- a number coerced to a double float for the paper width, in points
height -- a number coerced to a double float for the paper height, in points
Returns:
The new gtk:paper-size instance.
Details:
Creates a new gtk:paper-size instance by using PPD information. If the name argument is not a recognized PPD paper name, the displayname, width and height arguments are used to construct a custom gtk:paper-size instance.
See also:
2025-1-6
Function gtk:paper-size-new-from-ipp (name &optional width height)
Arguments:
name -- a string for the IPP paper name
width -- a number coerced to a double float for the paper width, in points
height -- a number coerced to a double float for the paper height, in points
Returns:
The new gtk:paper-size instance.
Details:
Creates a new gtk:paper-size instance by using PPD information. If the name argument is not a recognized IPP paper name, the width and height arguments are used to construct a custom gtk:paper-size instance.
See also:
2025-1-6
Function gtk:paper-size-new-custom (name displayname width height unit)
Arguments:
name -- a string for the paper name
displayname -- a string for the human readable name
width -- a number coerced to a double float for the paper width, in units of unit
height -- a number coerced to a double float for the paper height, in units of unit
unit -- a gtk:unit value for width and height, not :none
Returns:
The new gtk:paper-size instance.
Details:
Creates a new gtk:paper-size instance with the given parameters.
See also:
2025-1-6
Function gtk:paper-size-copy (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The new gtk:paper-size instance with the copy of size.
Details:
Copies an existing gtk:paper-size instance.
See also:
2025-1-6
Function gtk:paper-size-is-equal (size1 size2)
Arguments:
size1 -- a gtk:paper-size instance
size2 -- another gtk:paper-size instance
Returns:
True, if size1 and size2 represent the same paper size.
Details:
Compares two gtk:paper-size instances.
See also:
2025-1-6
Function gtk:paper-size-paper-sizes (custom)
Arguments:
custom -- a boolean whether to include custom paper sizes as defined in the page setup dialog
Returns:
The list of gtk:paper-size instances.
Details:
Creates a list of known paper sizes.
See also:
2025-1-6
Function gtk:paper-size-name (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The string with the name of the paper size.
Details:
Gets the name of the paper size.
See also:
2025-1-6
Function gtk:paper-size-display-name (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The string with the human readable name of the paper size.
Details:
Gets the human readable name of the paper size.
See also:
2025-1-6
Function gtk:paper-size-ppd-name (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The string with the PPD name of the paper size.
Details:
Gets the PPD name of the paper size, which may be nil.
See also:
2025-1-6
Function gtk:paper-size-width (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the paper width.
Details:
Gets the paper width of the paper size, in units of unit.
See also:
2025-1-6
Function gtk:paper-size-height (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the paper height.
Details:
Gets the paper height of the paper size, in units of unit.
See also:
2025-1-6
Function gtk:paper-size-is-ipp (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The boolean whether the paper size is an IPP paper size.
Details:
Returns true if the paper size is an IPP standard paper size.
See also:
2025-1-6
Function gtk:paper-size-is-custom (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The boolean whether size is a custom paper size.
Details:
Returns true if size is not a standard paper size.
See also:
2025-1-6
Function gtk:paper-size-set-size (size width height unit)
Arguments:
size -- a custom gtk:paper-size instance
width -- a number coerced to a double float for the new width in units of unit
height -- a number coerced to a double float for the new height in units of unit
unit -- a gtk:unit value for width and height
Details:
Changes the dimensions of a paper size to width x height.
See also:
2025-1-6
Function gtk:paper-size-default-top-margin (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the default top margin.
Details:
Gets the default top margin for the paper size.
See also:
2025-1-6
Function gtk:paper-size-default-bottom-margin (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the default bottom margin.
Details:
Gets the default bottom margin for the paper size.
See also:
2025-1-6
Function gtk:paper-size-default-left-margin (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the default left margin.
Details:
Gets the default left margin for the paper size.
See also:
2025-1-6
Function gtk:paper-size-default-right-margin (size unit)
Arguments:
size -- a gtk:paper-size instance
unit -- a gtk:unit value for the return value, not :none
Returns:
The double float with the default right margin.
Details:
Gets the default right margin for the paper size.
See also:
2025-1-6
Function gtk:paper-size-default ()
Returns:
The string with the name of the default paper size.
Details:
Returns the name of the default paper size, which depends on the current locale.
Examples:
(gtk:paper-size-default) => "iso_a4"    
See also:
2025-1-6
Function gtk:paper-size-new-from-key-file (keyfile group)
Arguments:
keyfile -- a g:key-file instance to retrieve the paper size from
group -- a string for the name of the group in the key file to read, or nil to read the first group
Returns:
The new gtk:paper-size instance with the restored paper size, or nil if an error occurred.
Details:
Reads a paper size from the group group in the key file keyfile.
See also:
2025-1-6
Function gtk:paper-size-new-from-gvariant (value)
Arguments:
value -- a g:variant parameter of "a{sv}" type
Returns:
The gtk:paper-size instance.
Details:
Deserialize a paper size from a g:variant parameter of "a{sv}" type in the format produced by the gtk:paper-size-to-gvariant function.
See also:
2025-1-6
Function gtk:paper-size-to-key-file (size keyfile groupname)
Arguments:
size -- a gtk:paper-size instance
keyfile -- a g:key-file instance to save the paper size to
groupname -- a string for the group name to add the settings to in keyfile
Details:
This function adds the paper size from size to keyfile.
See also:
2025-1-6
Function gtk:paper-size-to-gvariant (size)
Arguments:
size -- a gtk:paper-size instance
Returns:
The new g:variant parameter of "a{av}" type.
Details:
Serialize a paper size to a g:variant parameter of "a{sv}" type.
Examples:
(gtk:paper-size-to-gvariant (gtk:paper-size-new))
=> #.(SB-SYS:INT-SAP #X00F02070)
(g:variant-print * nil)
=> "{'PPDName': <'A4'>, 'DisplayName': <'A4'>, 'Width': <210.0>, 'Height': <297.0>}"    
See also:
2025-1-6

GtkPrintSettings

GEnum gtk:page-orientation
Declaration:
(gobject:define-genum "GtkPageOrienation" page-orientation
  (:export t
   :type-initializer "gtk_page_orientation_get_type")
  :portrait
  :landscape
  :reverse-portrait
  :reverse-landscape)  
Values:
:portrait
Portrait mode.
:landscape
Landscape mode.
:reverse-portrait
Reverse portrait mode.
:reverse-landscape
Reverse landscape mode.
Details:
See the gtk:print-settings-orientation function.
See also:
2024-2-17
GEnum gtk:print-duplex
Declaration:
(gobject:define-genum "GtkPrintDuplex" print-duplex
  (:export t
   :type-initializer "gtk_print_duplex_get_type")
  :simplex
  :horizontal
  :vertical)  
Values:
:simplex
No duplex.
:horizontal
Horizontal duplex.
:vertical
Vertical duplex.
Details:
See the gtk:print-settings-duplex function.
See also:
2024-2-17
GEnum gtk:print-quality
Declaration:
(gobject:define-genum "GtkPrintQuality" print-quality
  (:export t
   :type-initializer "gtk_print_quality_get_type")
  :low
  :normal
  :high
  :draft)  
Values:
:low
Low quality.
:normal
Normal quality.
:high
High quality.
:draft
Draft quality.
Details:
See the gtk:print-settings-quality function.
See also:
2024-2-17
GEnum gtk:number-up-layout
Declaration:
(gobject:define-genum "GtkNubmerUpLayout" number-up-layout
  (:export t
   :type-initializer "gtk_number_up_layout_get_type")
  (:left-to-right-top-to-bottom 0)
  (:left-to-right-bottom-to-top 1)
  (:right-to-left-bottom-to-top 2)
  (:right-to-left-top-to-bottom 3)
  (:top-to-bottom-left-to-right 4)
  (:top-to-bottom-right-to-left 5)
  (:bottom-to-top-left-to-right 6)
  (:bottom-to-top-right-to-left 7))  
Values:
:left-to-right-top-to-bottom
:left-to-right-bottom-to-top
:right-to-left-bottom-to-top
:right-to-left-top-to-bottom
:top-to-bottom-left-to-right
:top-to-bottom-right-to-left
:bottom-to-top-left-to-right
:bottom-to-top-right-to-left
Details:
Used to determine the layout of pages on a sheet when printing multiple pages per sheet.
See also:
2024-2-17
GEnum gtk:print-pages
Declaration:
(gobject:define-genum "GtkPrintPages" print-pages
  (:export t
   :type-initializer "gtk_print_pages_get_type")
  (:all 0)
  (:current 1)
  (:ranges 2)
  (:selection 3))  
Values:
:all
All pages.
:current
Current page.
:ranges
Range of pages.
:selection
Selected pages.
Details:
See also:
2024-2-17
GEnum gtk:page-set
Declaration:
(gobject:define-genum "GtkPageSet" page-set
  (:export t
   :type-initializer "gtk_page_set_get_type")
  (:all 0)
  (:even 1)
  (:odd 2))  
Values:
:all
All pages.
:even
Even pages.
:odd
Odd pages.
Details:
See the gtk:print-job-page-set function.
See also:
2024-2-17
Class gtk:print-settings
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A gtk:print-settings object represents the settings of a print dialog in a system independent way. The main use for this object is that once you have printed you can get a settings object that represents the settings the user chose, and the next time you print you can pass that object in so that the user does not have to re-set all his settings.

Its also possible to enumerate the settings so that you can easily save the settings for the next time your app runs, or even store them in a document. The predefined keys try to use shared values as much as possible so that moving such a document between systems still works.

The list of keys for a print setting:
"printer"                "orientation"              "paper-format"
"paper-width"            "paper-height"             "use-color"
"collate"                "reverse"                  "duplex"
"quality"                "n-copies"                 "number-up"
"number-up-layout"       "resolution"               "resolution-x"
"resolution-y"           "printer-lpi"              "scale"
"print-pages"            "page-ranges"              "page-set"
"default-source"         "media-type"               "dither"
"finishings"             "output-bin"               "output-dir"
"output-basename"        "output-file-format"       "output-uri"
"win32-driver-extra"     "win32-driver-version"  
See also:
2024-2-17
Function gtk:print-settings-new ()
Returns:
The new gtk:print-settings object.
Details:
Creates a new gtk:print-settings object.
See also:
2024-2-17
Function gtk:print-settings-copy (other)
Arguments:
other -- a gtk:print-settings object
Returns:
The newly allocated gtk:print-settings object with the copy of other.
Details:
Copies a gtk:print-settings object.
See also:
2024-2-17
Function gtk:print-settings-has-key (settings key)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
Returns:
True, if key has a value.
Details:
Returns true, if a value is associated with key.
See also:
2024-2-17
Function gtk:print-settings-get (settings key)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
Returns:
The string value for key.
Details:
Looks up the string value associated with key.
See also:
2024-2-17
Function gtk:print-settings-set (settings key value)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
value -- a string with a value, or nil
Details:
Associates value with key. If value is nil removes any value associated with key. This has the same effect as using the gtk:print-settings-unset function.
See also:
2024-2-17
Function gtk:print-settings-unset (settings key)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
Details:
Removes any value associated with key. This has the same effect as setting the value to nil.
See also:
2024-2-17
Callback gtk:print-settings-func
Syntax:
lambda (key value)
Arguments:
key -- a string with the key value
value -- a string with the value for key
Details:
The callback function that is called from the gtk:print-settings-foreach function.
See also:
2024-5-4
Function gtk:print-settings-foreach (settings func)
Arguments:
settings -- a gtk:print-settings object
func -- a gtk:print-settings-func callback function to call
Details:
Calls func for each key value pair of the print settings.
See also:
2024-2-17
Function gtk:print-settings-bool (settings key)
Syntax:
(gtk:print-settings-bool settings key) => value
(setf (gtk:print-settings-bool settings key) value)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
value -- a boolean value
Details:
The gtk:print-settings-bool function returns the boolean represented by the value that is associated with key. The (setf gtk:print-settings-bool) function sets key to a boolean value.

The string "true" represents true, any other string false.
See also:
2024-2-18
Function gtk:print-settings-double (settings key)
Syntax:
(gtk:print-settings-double settings key) => value
(setf (gtk:print-settings-double settings key) value)
Arguments:
settings -- a gtk:print-settings object
key -- a string for a key
value -- a double float
Details:
The gtk:print-settings-double function gets the double float for key, or 0. The function (setf gtk:print-settings-double) function sets key to a double float.
See also:
#2024-2-18
Function gtk:print-settings-double-with-default (settings key default)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
default -- a double float number with the default value
Returns:
The double float number associated with key.
Details:
Returns the double float number represented by the value that is associated with key, or default if the value does not represent a double float number. Double float numbers are parsed with the g_ascii_strtod() function.
See also:
#2024-2-18
Function gtk:print-settings-length (settings key unit)
Syntax:
(gtk:print-settings-length settings key unit) => value
(setf (gtk:print-settings-length settings key unit) value)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
unit -- a gtk:unit value with the unit of the return value
value -- a number with the length
Details:
The gtk:print-settings-length function returns the length value of key, converted to unit. The (setf gtk:print-settings-length) function associates a length in units of unit with key.
Examples:
 (setq settings (make-instance 'gtk:print-settings))
=> #<gtk:print-settings {1004A34623}>
 (setf (gtk:print-settings-length settings "paper-width" :mm) 100.0d0)
 (gtk:print-settings-length settings "paper-width" :mm)
=> 100.0d0    
See also:
2024-2-18
Function gtk:print-settings-int (settings key)
Syntax:
(gtk:print-settings-int settings key) => value
(setf (gtk:print-settings-int settings key) value)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
value -- an integer with the value
Details:
The gtk:print-settings-int function returns the integer for key, or 0. The (setf gtk:print-settings-int) function sets key to an integer.
See also:
#2024-2-18
Function gtk:print-settings-int-with-default (settings key default)
Arguments:
settings -- a gtk:print-settings object
key -- a string with a key
default -- an integer with the default value
Returns:
The integer for key.
Details:
Returns the value for key, interpreted as an integer, or the default value.
See also:
#2024-2-18
Function gtk:print-settings-printer (settings)
Syntax:
(gtk:print-settings-printer settings) => printer
(setf (gtk:print-settings-printer settings) printer)
Arguments:
settings -- a gtk:print-settings object
printer -- a string with the printer name
Details:
The gtk:print-settings-printer function obtains the value of the "printer" setting. The (setf gtk:print-settings-printer) function sets the "printer" setting.
See also:
#2024-2-18
Function gtk:print-settings-orientation (settings)
Syntax:
(gtk:print-settings-orientation settings) => orientation
(setf (gtk:print-settings-orientation settings) orientation)
Arguments:
settings -- a gtk:print-settings object
orientation -- a gtk:page-orientation value with the page orientation
Details:
The gtk:print-settings-orientation function gets the value of the "orientation" setting, converted to a gtk:page-orientation value. The (setf gtk:print-settings-orientation) function sets the value of the "orientation" setting.
See also:
#2024-2-18
Function gtk:print-settings-paper-size (settings)
Syntax:
(gtk:print-settings-paper-size settings) => size
(setf (gtk:print-settings-paper-size settings) size)
Arguments:
settings -- a gtk:print-settings object
size -- a gtk:paper-size instance with the paper size
Details:
The gtk:print-settings-paper-size function gets the value of "paper-format" setting, converted to a gtk:paper-size instance. The (setf gtk:print-settings-paper-size) function sets the value of the "paper-format", "paper-width", and "paper-height" settings.
Examples:
 (setq settings (make-instance 'gtk:print-settings))
=> #<gtk:print-settings {1001A0F643}>
 (setf (gtk:print-settings-paper-size settings) (gtk:paper-size-new "iso_a4"))
=> #<GTK-PAPER-SIZE {1001A244C3}>
 (gtk:print-settings-paper-size settings)
=> #<GTK-PAPER-SIZE {1001A24B63}>    
See also:
2024-2-18
Function gtk:print-settings-paper-width (settings unit)
Syntax:
(gtk:print-settings-paper-width settings unit) => width
(setf (gtk:print-settings-paper-width settings unit) width)
Arguments:
settings -- a gtk:print-settings object
unit -- a gtk:unit value with the unit for the return value
width -- a double float with the paper width
Details:
The gtk:print-settings-paper-width function gets the value of the "paper-width" setting converted to unit. The (setf gtk:print-settings-paper-width) function sets the value of "paper-width" setting.
See also:
#2024-2-18
Function gtk:print-settings-paper-height (settings unit)
Syntax:
(gtk:print-settings-paper-height settings unit) => height
(setf (gtk:print-settings-paper-height settings unit) height)
Arguments:
settings -- a gtk:print-settings object
unit -- a gtk:unit value with the unit for the return value
height -- a double float with the paper height
Details:
The gtk:print-settings-paper-height function gets the value of the "paper-height" setting, converted to unit. The (setf gtk:print-settings-paper-height) function sets the value of the "paper-height" setting.
See also:
#2024-2-18
Function gtk:print-settings-use-color (settings)
Syntax:
(gtk:print-settings-use-color settings) => use-color
(setf (gtk:print-settings-use-color settings) use-color)
Arguments:
settings -- a gtk:print-settings object
use-color -- a boolean whether to use color
Details:
The gtk:print-settings-use-color function gets the value of the "use-color" setting. The (setf gtk:print-settings-use-color) function sets the value of "use-color" setting.
See also:
#2024-2-18
Function gtk:print-settings-collate (settings)
Syntax:
(gtk:print-settings-collate settings) => collate
(setf (gtk:print-settings-collate settings) collate)
Arguments:
settings -- a gtk:print-settings object
collate -- a boolean whether to collate the output
Details:
The gtk:print-settings-collate function gets the value of the "collate" setting. The (setf gtk:print-settings-collate) function sets the value of the "collate" setting.
See also:
#2024-2-18
Function gtk:print-settings-reverse (settings)
Syntax:
(gtk:print-settings-reverse settings) => reverse
(setf (gtk:print-settings-reverse settings) reverse)
Arguments:
settings -- a gtk:print-settings object
reverse -- a boolean whether to reverse the output
Returns:
Whether to reverse the order of the printed pages.
Details:
The gtk:print-settings-reverse function gets the value of the "reverse" setting. The (setf gtk:print-settings-reverse) function sets the value of the "reserve" setting.
See also:
#2024-2-18
Function gtk:print-settings-duplex (settings)
Syntax:
(gtk:print-settings-duplex settings) => duplex
(setf (gtk:print-settings-duplex settings) duplex)
Arguments:
settings -- a gtk:print-settings object
duplex -- a gtk:print-duplex value
Details:
Whether to print the output in duplex. The gtk:print-settings-duplex function gets the value of the "duplex" setting. The (setf gtk:print-settings-duplex) function sets the value of the "duplex" setting.
See also:
#2024-2-18
Function gtk:print-settings-quality (settings)
Syntax:
(gtk:print-settings-quality settings) => quality
(setf (gtk:print-settings-quality settings) quality)
Arguments:
settings -- a gtk:print-settings object
quality -- a gtk:print-quality value
Details:
The gtk:print-settings-quality function gets the value of the "quality" setting. The (setf gtk:print-settings-quality) function sets the value of the "quality" setting.
See also:
#2024-2-18
Function gtk:print-settings-n-copies (settings)
Syntax:
(gtk:print-settings-n-copies settings) => n-copies
(setf (gtk:print-settings-n-copies settings) n-copies)
Arguments:
settings -- a gtk:print-settings object
n-copies -- an integer with the number of copies
Details:
The number of copies to print. The gtk:print-settings-n-copies function gets the value of the "n-copies" setting. The (setf gtk:print-settings-n-copies) function sets the value of the "n-copies" setting.
See also:
#2024-2-18
Function gtk:print-settings-number-up (settings)
Syntax:
(gtk:print-settings-number-up settings) => number-up
(setf (gtk:print-settings-number-up settings) number-up)
Arguments:
settings -- a gtk:print-settings object
number-up -- an integer with the number of pages per sheet
Details:
The number of pages per sheet. The gtk:print-settings-number-up function gets the value of the "number-up" setting. The (setf gtk:print-settings-number-up) function sets the value of the "number-up" setting.
See also:
#2024-2-18
Function gtk:print-settings-number-up-layout (settings)
Syntax:
(gtk:print-settings-number-up-layout settings) => number-up-layout
(setf (gtk:print-settings-number-up-layout settings) number-up-layout)
Arguments:
settings -- a gtk:print-settings object
number-up-layout -- a gtk:number-up-layout value
Details:
Layout of page in number-up mode. The gtk:print-settings-number-up-layout function gets the value of the "number-up-layout" setting. The (setf gtk:print-settings-number-up-layout) function sets the value of the "number-up-layout" setting.
See also:
#2024-2-18
Function gtk:print-settings-resolution (settings)
Syntax:
(gtk:print-settings-resolution settings) => resolution
(setf (gtk:print-settings-resolution settings) resolution)
Arguments:
settings -- a gtk:print-settings object
resolution -- an integer with the resolution in dpi
Details:
The resolution in dpi. The gtk:print-settings-resolution function gets the value of the "resolution" setting. The (setf gtk:print-settings-resolution) function sets the values of the "resolution", "resolution-x" and "resolution-y" settings.
See also:
#2024-2-18
Function gtk:print-settings-resolution-x (settings)
Arguments:
settings -- a gtk:print-settings object
Returns:
The integer with the horizontal resolution in dpi.
Details:
Gets the value of the "resolution-x" setting.
See also:
#2024-2-18
Function gtk:print-settings-resolution-y (settings)
Arguments:
settings -- a gtk:print-settings object
Returns:
The integer with the vertical resolution in dpi.
Details:
Gets the value of the "resolution-y" setting.
See also:
#2024-2-18
Function gtk:print-settings-printer-lpi (settings)
Syntax:
(gtk:print-settings-printer-lpi settings) => lpi
(setf (gtk:print-settings-printer-lip settings) lpi)
Arguments:
settings -- a gtk:print-settings object
lpi -- an integer with the resolution in lpi (lines per inch)
Details:
The resolution in lpi (lines per inch). The gtk:print-settings function gets the value of the "print-lpi" setting. The (setf gtk:print-settings-printer-lpi) function sets the values of the "printer-lpi" setting.
See also:
#2024-2-18
Function gtk:print-settings-scale (settings)
Syntax:
(gtk:print-settings-scale settings) => scale
(setf (gtk:print-settings-scale settings) scale)
Arguments:
settings -- a gtk:print-settings object
scale -- a double float with the scale in percent
Details:
The scale in percent. The gtk:print-settings-scale function gets the value of the "scale" setting. The (setf gtk:print-settings-scale) function sets the value of the "scale" setting.
See also:
#2024-2-18
Function gtk:print-settings-print-pages (settings)
Syntax:
(gtk:print-settings-print-pages settings) => pages
(setf (gtk:print-settings-print-pages settings) pages)
Arguments:
settings -- a gtk:print-settings object
pages -- a gtk:print-pages value
Details:
Which pages to print. The gtk:print-settings-print-pages function gets the value of the "print-pages" setting. The (setf gtk:print-settings-print-pages) function sets the value of the "print-pages" setting.
See also:
#2024-2-18
Function gtk:print-settings-page-ranges (settings)
Syntax:
(gtk:print-settings-page-ranges settings) => ranges
(setf (gtk:print-settings-page-ranges settings) ranges)
Arguments:
settings -- a gtk:print-settings object
ranges -- a list of pages ranges
Details:
The gtk:print-settings-page-ranges function gets the value of the "page-ranges" setting. The (setf gtk:print-settings-page-ranges) function sets the value of the "page-ranges" setting.
Examples:
 (setq settings (gtk:print-settings-new))
=> #<gtk:print-settings {1001929323}>
 (setf (gtk:print-settings-page-ranges settings) '((1) (15 20) (25)))
=> ((1) (15 20) (25))
 (gtk:print-settings-page-ranges settings)
=> ((1) (15 20) (25))    
See also:
#2024-2-18
Function gtk:print-settings-page-set (settings)
Syntax:
(gtk:print-settings-page-set settings) => page-set
(setf (gtk:print-settings-page-set settings) page-set)
Arguments:
settings -- a gtk:print-settings object
page-set -- a gtk:page-set value
Details:
The set of pages to print. The gtk:print-settings-page-set function gets the value of the "page-set" setting. The (setf gtk:print-settings-page-set) function sets the values of the "page-set" setting.
See also:
#2024-2-18
Function gtk:print-settings-default-source (settings)
Syntax:
(gtk:print-settings-default-source settings) => default-source
(setf (gtk:print-settings-default-source settings) default-source)
Arguments:
settings -- a gtk:print-settings object
default-source -- a string with the default source
Details:
The default source. The gtk:print-settings-default-source function gets the value of "default-source" setting. The (setf gtk:print-settings-default-source) function sets the value of the "default-source" setting.
See also:
#2024-2-18
Function gtk:print-settings-media-type (settings)
Syntax:
(gtk:print-settings-media-type settings) => media-type
(setf (gtk:print-settings-media-type settings) media-type)
Arguments:
settings -- a gtk:print-settings object
media-type -- a string with the media type
Details:
The gtk:print-settings-media-type function gets the value of the "media-type" setting. The (setf gtk:print-settings-media-type) function sets the value of the "media-type" setting. The set of media types is defined in PWG 5101.1-2002.
See also:
#2024-2-18
Function gtk:print-settings-dither (settings)
Syntax:
(gtk:print-settings-dither settings) => dither
(setf (gtk:print-settings-dither settings) dither)
Arguments:
settings -- a gtk:print-settings object
dither -- a string with the dithering that is used
Details:
The gtk:print-settings-dither function gets the value of the "dither" setting. The (setf gtk:print-settings-dither) function sets the value of the "dither" setting.
See also:
#2024-2-18
Function gtk:print-settings-finishings (settings)
Syntax:
(gtk:print-settings-finishings settings) => finishings
(setf (gtk:print-settings-finishings settings) finishings)
Arguments:
settings -- a gtk:print-settings object
finishings -- a string with the finishings
Details:
The gtk:print-settings-finishings gets the value of the "finishings" setting. The (setf gtk:print-settings-finishings) function sets the value of "finishing" setting.
See also:
#2024-2-18
Function gtk:print-settings-output-bin (settings)
Syntax:
(gtk:print-settings-output-bin settings) => output-bin
(setf (gtk:print-settings-output-bin settings) output-bin)
Arguments:
settings -- a gtk:print-settings object
output-bin -- a string with the output bin
Details:
The gtk:print-settings-output-bin function gets the value of the "output-bin" setting. The (setf gtk:print-settings-output-bin) function sets the value of the "output-bin" setting.
See also:
#2024-2-18
Function gtk:print-settings-new-from-file (path)
Arguments:
path -- a pathname or namestring with the file to read the settings from
Returns:
The restored gtk:print-settings object.
Details:
Reads the print settings from path. Returns a new gtk:print-settings object with the restored settings, or nil if an error occurred.
See also:
2024-11-21
Function gtk:print-settings-new-from-key-file (keyfile group)
Arguments:
keyfile -- a g:key-file instance to retrieve the settings from
group -- a string with the name of the group to use, or nil to use the default "Print Settings"
Returns:
The restored gtk:print-settings object.
Details:
Reads the print settings from the group group in the key file. Returns a new gtk:print-settings object with the restored settings, or nil if an error occurred.
See also:
2024-11-21
Function gtk:print-settings-new-from-gvariant (variant)
Arguments:
variant -- a a{sv} g:variant parameter
Returns:
The restored gtk:print-settings object.
Details:
Deserialize print settings from a a{sv} variant in the format produced by the gtk:print-settings-to-gvariant function.
Examples:
(let* ((variant (g:variant-parse "a{sv}"
                                 "{'scale': <'100'>,
                                   'number-up': <'1'>,
                                   'n-copies': <'1'>,
                                   'page-ranges': <'0-11'>,
                                   'page-set': <'all'>,
                                   'printer': <'In Datei drucken'>,
                                   'print-pages': <'ranges'>,
                                   'reverse': <'false'>,
                                   'collate': <'false'>,
                                   'output-file-format': <'pdf'>}"))
       (settings (gtk:print-settings-new-from-gvariant variant)))
  (g:variant-print (gtk:print-settings-to-gvariant settings) nil))
=> "{'scale': <'100'>, 'number-up': <'1'>, 'n-copies': <'1'>,
      'page-ranges': <'0-11'>, 'page-set': <'all'>,
      'printer': <'In Datei drucken'>, 'print-pages': <'ranges'>,
      'reverse': <'false'>, 'collate': <'false'>,
      'output-file-format': <'pdf'>}"    
See also:
2024-2-18
Function gtk:print-settings-load-file (settings path)
Arguments:
settings -- a gtk:print-settings object
path -- a pathname or namestring with the filename to read the settings from
Returns:
True on success.
Details:
Reads the print settings from path.
See also:
2024-11-21
Function gtk:print-settings-load-key-file (settings keyfile group)
Arguments:
settings -- a gtk:print-settings object
keyfile -- a g:key-file instance to retrieve the settings from
group -- a string with the name of the group to use, or nil to use the default "Print Settings"
Returns:
True on success.
Details:
Reads the print settings from the group group in the key file.
See also:
2024-11-21
Function gtk:print-settings-to-file (settings path)
Arguments:
settings -- a gtk:print-settings object
path -- a pathname or namestring with the file to save to
Returns:
True on success.
Details:
This function saves the print settings from settings to path.
See also:
2024-11-21
Function gtk:print-settings-to-key-file (settings keyfile group)
Arguments:
settings -- a gtk:print-settings object
keyfile -- a g:key-file instance to save the print settings to
group -- a string with the group to add the settings to in the key file, or nil to use the default "Print Settings" group.
Details:
This function adds the print settings to the key file.
See also:
2024-2-18
Function gtk:print-settings-to-gvariant (settings)
Arguments:
settings -- a gtk:print-settings object
Returns:
The new g:variant parameter of a{sv} type.
Details:
Serialize print settings to a a{sv} variant.
See also:
2024-2-18

GtkPageSetup

Class gtk:page-setup
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:page-setup object stores the page size, orientation and margins. The idea is that you can get one of these from the page setup dialog and then pass it to the gtk:print-operation object when printing. The benefit of splitting this out of the gtk:print-settings object is that these affect the actual layout of the page, and thus need to be set long before user prints.

The margins specified in this object are the "print margins". These are the parts of the page that the printer cannot print on. These are different from the layout margins used by a word processor. They are typically used to determine the minimal size for the layout margins.

To obtain a gtk:page-setup object use the function gtk:page-setup-new to get the defaults, or use the function gtk:print-run-page-setup-dialog to show the page setup dialog and receive the resulting page setup.
Examples:
A page setup dialog.
(defun do-page-setup (settings page-setup)
  (when (not settings)
    ;; Set default print settings
    (setf settings (gtk:print-settings-new)))
  ;; Return the new page setup from the dialog
  (gtk:print-run-page-setup-dialog window page-setup settings))    
See also:
2024-4-30
Function gtk:page-setup-new ()
Returns:
The new gtk:page-setup object.
Details:
Creates a new page setup.
See also:
2024-4-30
Function gtk:page-setup-new-from-file (path)
Arguments:
path -- a pathname or namestring with the file to read the page setup from
Returns:
The restored gtk:page-setup object.
Details:
Reads the page setup from a file. Returns a new gtk:page-setup object with the restored page setup, or nil if an error occurred. See the gtk:page-setup-to-file function.
See also:
2024-11-21
Function gtk:page-setup-new-from-key-file (keyfile group)
Arguments:
keyfile -- a g:key-file instance to retrieve the page setup from
group -- a string with the name of the group in the key file to read, or nil to use the default name "Page Setup"
Returns:
The restored gtk:page-setup object.
Details:
Reads the page setup from the group group in the key file. Returns a new gtk:page-setup object with the restored page setup, or nil if an error occurred.
See also:
2024-11-21
Function gtk:page-setup-new-from-gvariant (variant)
Arguments:
variant -- a g:variant parameter of a{sv} type
Returns:
The new gtk:page-setup object.
Details:
Deserialize a page setup from a a{sv} variant in the format produced by the gtk:page-setup-to-gvariant function.
See also:
2024-4-30
Function gtk:page-setup-copy (setup)
Arguments:
setup -- a gtk:page-setup object to copy
Returns:
The gtk:page-setup object with the copy of setup.
Details:
Copies a page setup.
See also:
2024-4-30
Function gtk:page-setup-orientation (setup)
Syntax:
(gtk:page-setup-orientation setup) => orientation
(setf (gtk:page-setup-orientation setup) orientation)
Arguments:
setup -- a gtk:page-setup object
orientation -- a gtk:page-orientation value
Details:
The gtk:page-setup-orientation function gets the page orientation of the page setup object. The (setf gtk:page-setup-orientation) function sets the page orientation. Possible values are :portrait and :landscape.
Examples:
Get the default page orientation.
(let ((setup (gtk:page-setup-new)))
  (gtk:page-setup-orientation setup))
=> :PORTRAIT    
See also:
2024-4-30
Function gtk:page-setup-paper-size (setup)
Syntax:
(gtk:page-setup-paper-size setup) => size
(setf (gtk:page-setup-paper-size setup) size)
Arguments:
setup -- a gtk:page-setup object
size -- a gtk:paper-size instance
Details:
The gtk:page-setup-paper-size function gets the paper size of the page setup object. The (setf gtk:page-setup-paper-size) function sets the paper size without changing the margins. See also the gtk:page-setup-set-paper-size-and-default-margins function.
See also:
2024-4-30
Function gtk:page-setup-top-margin (setup unit)
Syntax:
(gtk:page-setup-top-margin setup unit) => margin
(setf (gtk:page-setup-top-margin setup unit) margin)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value
margin -- a number coerced to a double float with the top margin in units of unit
Details:
The gtk:page-setup-top-margin function gets the top margin of the page setup in units of unit. The (setf gtk:page-setup-top-margin) function sets the top margin.
See also:
2024-4-30
Function gtk:page-setup-bottom-margin (setup unit)
Syntax:
(gtk:page-setup-bottom-margin setup unit) => margin
(setf (gtk:page-setup-bottom-margin setup unit) margin)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value
margin -- a number coerced to a double float with the bottom margin in units of unit
Details:
The gtk:page-setup-bottom-margin function gets the bottom margin of the page setup in units of unit. The (setf gtk:page-setup-bottom-margin) function sets the bottom margin.
See also:
2024-4-30
Function gtk:page-setup-left-margin (setup unit)
Syntax:
(gtk:page-setup-left-margin setup unit) => margin
(setf (gtk:page-setup-left-margin setup unit) margin)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value
margin -- a number coerced to a double float with the left margin in units of unit
Details:
The gtk:page-setup-left-margin function gets the left margin of the page setup in units of unit. The (setf gtk:page-setup-left-margin) function sets the left margin.
See also:
2024-4-30
Function gtk:page-setup-right-margin (setup unit)
Syntax:
(gtk:page-setup-right-margin setup unit) => margin
(setf (gtk:page-setup-right-margin setup unit) margin)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value
margin -- a number coerced to a double float with the right margin in units of unit
Details:
The gtk:page-setup-right-margin function gets the right margin of the page setup in units of unit. The (setf gtk:page-setup-right-margin) function sets the right margin.
See also:
2024-4-30
Function gtk:page-setup-set-paper-size-and-default-margins (setup size)
Arguments:
setup -- a gtk:page-setup object
size -- a gtk:paper-size instance
Details:
Sets the paper size of the page setup and modifies the margins according to the new paper size.
See also:
2024-4-30
Function gtk:page-setup-paper-width (setup unit)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value for the return value
Returns:
The double float with the paper width.
Details:
Returns the paper width of the page setup in units of unit. Note that this function takes orientation, but not margins into consideration. See also the gtk:page-setup-page-width function.
See also:
2024-4-30
Function gtk:page-setup-paper-height (setup unit)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value for the return value
Returns:
The double float with the paper height.
Details:
Returns the paper height of the page setup in units of unit. Note that this function takes orientation, but not margins into consideration. See also the gtk:page-setup-page-height function.
See also:
2024-4-30
Function gtk:page-setup-page-width (setup unit)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value for the return value
Returns:
The double float with the page width.
Details:
Returns the page width of the page setup in units of unit. Note that this function takes orientation and margins into consideration. See also the gtk:page-setup-paper-width function.
See also:
2024-4-30
Function gtk:page-setup-page-height (setup unit)
Arguments:
setup -- a gtk:page-setup object
unit -- a gtk:unit value for the return value
Returns:
The double float with the page height.
Details:
Returns the page height of the page setup in units of unit. Note that this function takes orientation and margins into consideration. See also the gtk:page-setup-paper-height function.
See also:
2024-4-30
Function gtk:page-setup-load-file (setup path)
Arguments:
setup -- a gtk:page-setup object
path -- a pathname or namestring with the file to read the page setup from
Returns:
True on success.
Details:
Reads the page setup from a file. See also the gtk:page-setup-to-file function.
See also:
2024-11-21
Function gtk:page-setup-load-key-file (setup keyfile group)
Arguments:
setup -- a gtk:page-setup object
keyfile -- a g:key-file instance to retrieve the page setup from
group -- a string with the name of the group in the key file to read, or nil to use the default name "Page Setup"
Returns:
True on success.
Details:
Reads the page setup from the group group in the key file.
See also:
2024-11-21
Function gtk:page-setup-to-file (setup path)
Arguments:
setup -- a gtk:page-setup object
path -- a pathname or namestring with the file to save to
Returns:
True on success.
Details:
The function saves the information from the page setup to a file.
See also:
2024-11-21
Function gtk:page-setup-to-key-file (setup keyfile group)
Arguments:
setup -- a gtk:page-setup object
keyfile -- a g:key-file instance to save the page setup to
group -- a string with the group to add the settings to in the key file, or nil to use the default name "Page Setup"
Details:
The function adds the page setup from the page setup to a key file.
See also:
2024-4-30
Function gtk:page-setup-to-gvariant (setup)
Arguments:
setup -- a gtk:page-setup object
Returns:
The new g:variant parameter of a{sv} type.
Details:
Serialize the page setup to a a{sv} variant.
See also:
2024-4-30

GtkPrinter

Class gtk:print-backend
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The print backend.
See also:
2024-7-6
Class gtk:printer
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accepting-jobs
The accepting-jobs property of type :boolean (Read)
True if the printer is accepting jobs.
Default value: true
accepts-pdf
The accepts-pdf property of type :boolean (Read / Write / Construct Only)
True if the printer can accept PDF.
Default value: false
accepts-ps
The accepts-ps property of type :boolean (Read / Write / Construct Only)
True if the printer can accept PostScript.
Default value: true
backend
The backend property of type gtk:print-backend (Read / Write / Construct Only)
Backend for the printer.
icon-name
The icon-name property of type :string (Read)
The icon name to use for the printer.
Default value: ""
is-virtual
The is-virtual property of type :boolean (Read / Write / Construct)
False if this represents a real hardware printer.
Default value: false
job-count
The job-count property of type :int (Read)
The number of jobs queued in the printer.
Allowed values: >= 0
Default value: 0
location
The location property of type :string (Read)
The location of the printer.
Default value: ""
name
The name property of type :string (Read / Write / Construct)
The name of the printer.
Default value: ""
paused
The paused property of type :boolean (Read)
True if this printer is paused. A paused printer still accepts jobs, but it does not print them.
Default value: false
state-message
The state-message property of type :string (Read)
The string giving the current state of the printer.
Default value: ""
Returned by:
Slot Access Functions:
Details:
The gtk:printer object represents a printer. You only need to deal directly with printers if you use the non-portable gtk:print-unix-dialog API.

The gtk:printer object allows to get status information about the printer, such as its description, its location, the number of queued jobs, etc. Most importantly, the gtk:printer object can be used to create a gtk:print-job object, which lets you print to the printer.
Signal Details:
The "details-acquired" signal
lambda (printer success)    :run-last      
printer
The gtk:printer object on which the signal is emitted.
success
True if the details were successfully acquired.
Gets emitted in response to a request for detailed information about a printer from the print backend. The success parameter indicates if the information was actually obtained.
See also:
2024-7-6
Accessor gtk:printer-accepting-jobs (object)
Syntax:
(gtk:printer-accepting-jobs object) => accepting-jobs
Arguments:
object -- a gtk:printer object
accepting-jobs -- a boolean whether the printer is accepting jobs
Details:
Accessor of the accepting-jobs slot of the gtk:printer class.
See also:
2024-7-6
Accessor gtk:printer-accepts-pdf (object)
Syntax:
(gtk:printer-accepts-pdf object) => accepts-pdf
Arguments:
object -- a gtk:printer object
accepts-pdf -- a boolean whether the printer can accept PDF
Details:
Accessor of the accepts-pdf slot of the gtk:printer class. Returns whether the printer accepts input in PDF format.
See also:
2024-7-6
Accessor gtk:printer-accepts-ps (object)
Syntax:
(gtk:printer-accepts-ps object) => accepts-ps
Arguments:
object -- a gtk:printer object
accepts-ps -- a boolean whether the printer can accept PostScript
Details:
Accessor of the accepts-ps slot of the gtk:printer class. Returns whether the printer accepts input in PostScript format.
See also:
2024-7-6
Accessor gtk:printer-backend (object)
Syntax:
(gtk:printer-backend object) => backend
Arguments:
object -- a gtk:printer object
backend -- a gtk:print-backend object
Returns:
The gtk:print-backend backend of the printer.
Details:
Accessor of the backend slot of the gtk:printer class. Returns the backend of the printer.
See also:
2024-7-6
Accessor gtk:printer-icon-name (object)
Syntax:
(gtk:printer-icon-name object) => icon-name
Arguments:
object -- a gtk:printer object
icon-name -- a string with the icon name
Details:
Accessor of the icon-name slot of the gtk:printer class. Gets the name of the icon to use for the printer.
See also:
2024-7-6
Accessor gtk:printer-is-virtual (object)
Syntax:
(gtk:printer-is-virtual object) => is-virtual
Arguments:
object -- a gtk:printer object
is-virtual -- a boolean whether the printer is real hardware printer
Details:
Accessor of the is-virtual slot of the gtk:printer class. Returns whether the printer is virtual, that is, does not represent actual printer hardware, but something like a CUPS class.
See also:
2024-7-6
Accessor gtk:printer-job-count (object)
Syntax:
(gtk:printer-job-count object) => count
Arguments:
object -- a gtk:printer object
count -- an integer with the number of jobs queued on the printer
Details:
Accessor of the job-count slot of the gtk:printer class. Gets the number of jobs currently queued on the printer.
See also:
2024-7-6
Accessor gtk:printer-location (object)
Syntax:
(gtk:printer-location object) => location
Arguments:
object -- a gtk:printer object
location -- a string with the location of the printer
Details:
Accessor of the location slot of the gtk:printer class. Returns a description of the location of the printer.
See also:
2024-7-6
Accessor gtk:printer-name (object)
Syntax:
(gtk:printer-name object) => name
Arguments:
object -- a gtk:printer object
name -- a string with the name of the printer
Details:
Accessor of the name slot of the gtk:printer class. Returns the name of the printer.
See also:
2024-7-6
Accessor gtk:printer-paused (object)
Syntax:
(gtk:printer-paused object) => paused
Arguments:
object -- a gtk:printer object
paused -- a boolean whether the printer is paused
Details:
Accessor of the paused slot of the gtk:printer class.
See also:
2024-7-6
Accessor gtk:printer-state-message (object)
Syntax:
(gtk:printer-state-message object) => message
Arguments:
object -- a gtk:printer object
message -- a string with the current state of the printer
Details:
Accessor of the state-message slot of the gtk:printer class. Returns the state message describing the current state of the printer.
See also:
2024-7-6
Function gtk:printer-new (name backend virtual)
Arguments:
name -- a string for the name of the printer
backend -- a gtk:print-backend object
virtual -- a boolean whether the printer is virtual
Returns:
The new gtk:printer object.
Details:
Creates a new printer.
See also:
2025-3-30
Function gtk:printer-description (printer)
Arguments:
printer -- a gtk:printer object
Returns:
The string with the description of printer.
Details:
Gets the description of the printer.
See also:
2024-7-6
Function gtk:printer-is-active (printer)
Arguments:
printer -- a gtk:printer object
Returns:
True if printer is active.
Details:
Returns whether the printer is currently active, that is accepts new jobs.
See also:
2024-7-6
Function gtk:printer-is-paused (printer)
Arguments:
printer -- a gtk:printer object
Returns:
True if printer is paused.
Details:
Returns whether the printer is currently paused. A paused printer still accepts jobs, but it is not printing them.
See also:
2024-7-6
Function gtk:printer-is-accepting-jobs (printer)
Arguments:
printer -- a gtk:printer object
Returns:
True if printer is accepting jobs.
Details:
Returns whether the printer is accepting jobs.
See also:
2024-7-6
Function gtk:printer-is-default (printer)
Arguments:
printer -- a gtk:printer object
Returns:
True if printer is the default.
Details:
Returns whether the printer is the default printer.
See also:
2024-7-6
Function gtk:printer-list-papers (printer)
Arguments:
printer -- a gtk:printer object
Returns:
The list of gtk:page-setup objects.
Details:
Lists all the paper sizes the printer supports. This will return an empty list unless the details of the printer are available, see the gtk:printer-has-details and gtk:printer-request-details functions.
See also:
2024-7-6
Function gtk:printer-compare (printer1 printer2)
Arguments:
printer1 -- a gtk:printer object
printer2 -- another gtk:printer object
Returns:
0 if the printer match, a negative value if a < b, or a positive value if a > b.
Details:
Compares two printers.
See also:
2024-7-6
Function gtk:printer-has-details (printer)
Arguments:
printer -- a gtk:printer object
Returns:
True if details for printer are available.
Details:
Returns whether printer details are available.
See also:
2024-7-6
Function gtk:printer-request-details (printer)
Arguments:
printer -- a gtk:printer object
Details:
Requests printer details for printer. When the details are available, the "details-acquired" signal will be emitted on the printer.
See also:
2024-7-6
Function gtk:printer-capabilities (printer)
Arguments:
printer -- a gtk:printer object
Returns:
The gtk:print-capabilities value with the capabilities of the printer.
Details:
Returns the capabilities of the printer. This is useful when you are using the manual-capabilities setting of the gtk:print-unix-dialog widget and need to know which settings the printer can handle and which you must handle yourself.

This will return 0 unless the details of the printer are available, see the gtk:printer-has-details and gtk:printer-request-details functions.
See also:
2024-7-6
Function gtk:printer-default-page-size (printer)
Arguments:
printer -- a gtk:printer object
Returns:
The gtk:page-setup object with the default page size of the printer.
Details:
Returns the default page size of the printer.
See also:
2024-7-6
Function gtk:printer-hard-margins (printer)
Arguments:
printer -- a gtk:printer object
Returns:
top -- a double float with the top margin
bottom -- a double float with the bottom margin
left -- a double float with the left margin in
right -- a double float with the right margin
Details:
Retrieve the hard margins of the printer, that is the margins that define the area at the borders of the paper that the printer cannot print to.
Notes:
This will not succeed unless the details of the printer are available, see the gtk:printer-has-details and gtk:printer-request-details functions.
See also:
2024-7-6
Function gtk:printer-hard-margins-for-paper-size (printer size)
Arguments:
printer -- a gtk:printer object
size -- a gtk:paper-size instance
Returns:
top -- a double float with the top margin
bottom -- a double float with the bottom margin
left -- a double float with the left margin
right -- a double float with the right margin
Details:
Retrieve the hard margins of printer for size. The hard margins define the area at the borders of the paper that the printer cannot print to.
Notes:
This will not succeed unless the details of the printer are available, see the gtk:printer-has-details and gtk:printer-request-details function.
See also:
2024-7-6
Callback gtk:printer-func
Syntax:
lambda (printer) => result
Arguments:
widget -- a gtk:printer object
result -- true to stop the enumeration, false to continue
Details:
The type of function passed to the gtk:enumerate-printers function.
See also:
2024-7-6
Function gtk:enumerate-printers (func wait)
Arguments:
func -- a gtk:printer-func callback function to call for each printer
wait -- if true, wait in a recursive main loop until all printers are enumerated, otherwise return early
Details:
Calls a function for all printers. If func returns true, the enumeration is stopped.
See also:
2024-7-6

GtkPrintJob

Class gtk:print-job
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
page-setup
The page-setup property of type gtk:page-setup (Read / Write / Construct Only)
The page setup.
printer
The printer property of type gtk:printer (Read / Write / Construct Only)
The printer to print the job to.
settings
The settings property of type gtk:print-settings (Read / Write / Construct Only)
The printer settings.
title
The title property of type :string (Read / Write / Construct Only)
The title of the print job.
Default value: nil
track-print-status
The track-print-status property of type :boolean (Read / Write)
True if the print job will continue to emit "status-changed" signals after the print data has been sent to the printer or print server.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:print-job object represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable gtk:print-unix-dialog API.

Use the gtk:print-job-surface function to obtain the Cairo surface onto which the pages must be drawn. Use the gtk:print-job-send function to send the finished job to the printer. If you are not using Cairo, the gtk:print-job object also supports printing of manually generated PostScript. This can be done using the gtk:print-job-set-source-file function.
Notes:
It is an error to use the make-instance method to create a gtk:print-job object from the Lisp side. You must use the gtk:print-job-new function.
Signal Details:
The "status-changed" signal
lambda (job)    :run-last      
job
The gtk:print-job object on which the signal was emitted.
Gets emitted when the status of a job changes. The signal handler can use the gtk:print-job-status function to obtain the new status.
See also:
2025-3-30
Accessor gtk:print-job-page-setup (object)
Syntax:
(gtk:print-job-page-setup object) => setup
Arguments:
object -- a gtk:print-job object
setup -- a gtk:page-setup object
Details:
Accessor of the page-setup slot of the gtk:print-job class.
See also:
2024-7-7
Accessor gtk:print-job-printer (object)
Syntax:
(gtk:print-job-printer object) => printer
Arguments:
object -- a gtk:print-job object
printer -- a gtk:printer object
Details:
Accessor of the printer of the gtk:print-job class. Gets the printer of the print job.
See also:
2024-7-7
Accessor gtk:print-job-settings (object)
Syntax:
(gtk:print-job-settings object) => settings
Arguments:
object -- a gtk:print-job object
settings -- a gtk:print-settings object
Details:
Accessor of the settings slot of the gtk:print-job class. Gets the print settings of the print job.
See also:
2024-7-7
Accessor gtk:print-job-title (object)
Syntax:
(gtk:print-job-title object) => title
Arguments:
object -- a gtk:print-job object
title -- a string with the job title.
Details:
Accessor of the title slot of the gtk:print-job class. Gets the job title.
See also:
2024-7-7
Accessor gtk:print-job-track-print-status (object)
Syntax:
(gtk:print-job-track-print-status object) => status
(setf (gtk:print-job-track-print-status object) status)
Arguments:
object -- a gtk:print-job object
status -- true to track status after printing
Details:
Accessor of the track-print-status slot of the gtk:print-job class. The gtk:print-job-track-print-status function returns whether jobs will be tracked after printing.

If the status argument is true, the print job will try to continue report on the status of the print job in the printer queues and printer.

This can allow your application to show things like "out of paper" issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed.
See also:
2024-7-7
Function gtk:print-job-new (title printer settings setup)
Arguments:
title -- a string for the job title
printer -- a gtk:printer object
settings -- a gtk:print-settings object
setup -- a gtk:page-setup object
Returns:
The new gtk:print-job object.
Details:
Creates a new gtk:print-job object.
See also:
2025-3-30
Function gtk:print-job-status (job)
Arguments:
job -- a gtk:print-job object
Returns:
The gtk:print-status value with the status of job.
Details:
Gets the status of the print job.
See also:
2024-7-7
Function gtk:print-job-set-source-file (job filename)
Arguments:
job -- a gtk:print-job object
filename -- a pathname or namestring with the file to be printed
Returns:
False if an error occurred.
Details:
Make the print job send an existing document to the printing system. The file can be in any format understood by the platforms printing system, typically PostScript, but on many platforms PDF may work too. See the gtk:printer-accepts-pdf and gtk:printer-accepts-ps functions.
See also:
2024-11-21
Function gtk:print-job-surface (job)
Arguments:
job -- a gtk:print-job object
Returns:
The cairo:surface-t instance for the Cairo surface of job.
Details:
Gets a Cairo surface onto which the pages of the print job should be rendered.
See also:
2024-11-21
Callback gtk:print-job-complete-func
Syntax:
lambda (job)
Arguments:
job -- a gtk:print-job object
Details:
The type of callback that is passed to the gtk:print-job-send function. It is called when the print job has been completely sent.
See also:
2024-7-7
Function gtk:print-job-send (job func)
Arguments:
job -- a gtk:print-job object
func -- a gtk:print-job-complete-func callback function to call when the job completes or an error occurs
Details:
Sends the print job off to the printer.
See also:
2024-7-7
Function gtk:print-job-pages (job)
Syntax:
(gtk:print-job-pages job) => pages
(setf (gtk:print-job-pages job) pages)
Arguments:
job -- a gtk:print-job object
pages -- a gtk:print-pages setting
Details:
The gtk:print-job-pages function gets the pages setting for the print job. The (setf gtk:print-job-pages) function sets the pages setting for the print job.
See also:
2024-7-7
Function gtk:print-job-page-ranges (job)
Syntax:
(gtk:print-job-page-ranges job) => ranges
(setf (gtk:print-job-page-ranges job) ranges)
Arguments:
job -- a gtk:print-job object
ranges -- a list of integers with the page ranges
Details:
Accessor of the page ranges for the print job. The gtk:print-job-page-ranges function gets the page ranges for the print job. The (setf gtk:print-job-page-ranges) function sets the page ranges. See the gtk:print-settings-page-ranges function.
See also:
2024-7-7
Function gtk:print-job-page-set (job)
Syntax:
(gtk:print-job-page-set job) => page-set
(setf (gtk:print-job-page-set job) page-set)
Arguments:
job -- a gtk:print-job object
page-set -- a gtk:page-set setting
Details:
The gtk:print-job-page-set function gets the setting for the print job. The (setf gtk:print-job-page-set) function sets the setting for the print job.
See also:
2024-7-7
Function gtk:print-job-num-copies (job)
Syntax:
(gtk:print-job-num-copies job) => num-copies
(setf (gtk:print-job-num-copies job) num-copies)
Arguments:
job -- a gtk:print-job object
num-copies -- an integer with the number of copies
Details:
Accessor of the number of copies for the print job. The gtk:print-job-num-copies function gets the number of copies of the print job. The (setf gtk:print-job-num-copies) function sets the number of copies for the print job.
See also:
2024-7-7
Function gtk:print-job-scale (job)
Syntax:
(gtk:print-job-scale job) => scale
(setf (gtk:print-job-scale job) scale)
Arguments:
job -- a gtk:print-job object
scale -- a number coerce to a double float with the scale
Details:
The gtk:print-job-scale function gets the scale for the print job, where 1.0 means unscaled. The (setf gtk:print-job-scale) function sets the scale for the print job.
See also:
2024-7-7
Function gtk:print-job-n-up (job)
Syntax:
(gtk:print-job-n-up job) => n-up
(setf (gtk:print-job-n-up job) n-up)
Arguments:
job -- a gtk:print-job object
n-up -- an unsigned integer with the n-up value
Details:
The gtk:print-job-n-up function gets the n-up setting for the print job. The (setf gtk:print-job-n-up) function sets the n-up setting for the print job.
See also:
2024-7-7
Function gtk:print-job-n-up-layout (job)
Syntax:
(gtk:print-job-n-up-layout job) => layout
(setf (gtk:print-job-n-up-layout job) layout)
Arguments:
job -- a gtk:print-job object
layout -- a gtk:number-up-layout value with the layout setting
Details:
The gtk:print-job-n-up-layout function gets the layout setting for the print job. The (setf gtk:print-job-n-up-layout) function sets the layout setting for the print job.
See also:
2024-7-7
Function gtk:print-job-rotate (job)
Syntax:
(gtk:print-job-rotate job) => rotate
(setf (gtk:print-job-rotate job) rotate)
Arguments:
job -- a gtk:print-job object
rotate -- a boolean whether to print rotated
Details:
The gtk:print-job-rotate function gets whether the job is printed rotated. The (setf gtk:print-job-rotate) function sets whether the job is printed rotated.
See also:
2024-7-7
Function gtk:print-job-collate (job)
Syntax:
(gtk:print-job-collate job) => collate
(setf (gtk:print-job-collate job) collate)
Arguments:
job -- a gtk:print-job object
collate -- a boolean whether the job is printed collated
Details:
The gtk:print-job-collate function gets whether the job is printed collated. The (setf gtk:print-job-collate) function sets whether the job is printed collated.
See also:
2024-7-7
Function gtk:print-job-reverse (job)
Syntax:
(gtk:print-job-reverse job) => reverse
(setf (gtk:print-job-reverse job) reverse)
Arguments:
job -- a gtk:print-job object
reverse -- a boolean whether the job is printed reversed
Details:
The gtk:print-job-reverse function gets whether the job is printed reversed. The (setf gtk:print-job-reverse) function sets whether the job is printed reversed.
See also:
2024-7-7

GtkPrintUnixDialog

GFlags gtk:print-capabilities
Declaration:
(gobject:define-gflags "GtkPrintCapabilities" print-capabilities
  (:export t
   :type-initializer "gtk_print_capabilities_get_type")
  (:page-set         #.(ash 1 0))
  (:copies           #.(ash 1 1))
  (:collate          #.(ash 1 2))
  (:reverse          #.(ash 1 3))
  (:scale            #.(ash 1 4))
  (:generate-pdf     #.(ash 1 5))
  (:generate-ps      #.(ash 1 6))
  (:preview          #.(ash 1 7))
  (:number-up        #.(ash 1 8))
  (:number-up-layout #.(ash 1 9)))  
Values:
:page-set
Print dialog will offer printing even/odd pages.
:copies
Print dialog will allow to print multiple copies.
:collate
Print dialog will allow to collate multiple copies.
:reverse
Print dialog will allow to print pages in reverse order.
:scale
Print dialog will allow to scale the output.
:generate-pdf
The program will send the document to the printer in PDF format.
:generate-ps
The program will send the document to the printer in Postscript format.
:preview
Print dialog will offer a preview.
:number-up
Print dialog will offer printing multiple pages per sheet.
:up-layout
Print dialog will allow to rearrange pages when printing multiple pages per sheet.
Details:
A flags for specifying which features the print dialog should offer. If neither the :generate-pdf nor the :generate-ps value is specified, GTK assumes that all formats are supported.
See also:
2024-2-18
Class gtk:print-unix-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
current-page
The current-page property of type :int (Read / Write)
The current page in the document.
Allowed values: >= -1
Default value: -1
embed-page-setup
The embed-page-setup property of type :boolean (Read / Write)
True if page setup combos are embedded in the print dialog.
Default value: false
has-selection
The has-selection property of type :boolean (Read / Write)
Whether the application has a selection.
Default value: false
manual-capabilities
The manual-capabilities property of type gtk:print-capabilities (Read / Write)
Capabilities the application can handle.
page-setup
The page-setup property of type gtk:page-setup (Read / Write)
The page setup to use.
print-settings
The print-settings property of type gtk:print-settings (Read / Write)
The print settings used for initializing the dialog.
selected-printer
The selected-printer property of type gtk:printer (Read)
The printer which is selected.
support-selection
The support-selection property of type :boolean (Read / Write)
Whether the dialog supports selection.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:print-unix-dialog widget implements a print dialog for platforms which do not provide a native print dialog, like Unix. It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API.

Figure: GtkPrintUnixDialog

In order to print something with the gtk:print-unix-dialog widget, you need to use the gtk:print-unix-dialog-selected-printer function to obtain a gtk:printer object and use it to construct a gtk:print-job object using the gtk:print-job-new function.

The gtk:print-unix-dialog widget uses the following response values:
:ok
For the "Print" button.
:apply
For the "Preview" button.
:cancel
For the "Cancel" button.
GtkPrintUnixDialog as GtkBuildable:
The gtk:print-unix-dialog implementation of the gtk:buildable interface exposes its notebook internal children with the name "notebook".

Example: A gtk:print-unix-dialog UI definition fragment.
<object class="GtkPrintUnixDialog" id="dialog1">
  <child internal-child="notebook">
    <object class="GtkNotebook" id="notebook">
      <child>
        <object class="GtkLabel" id="tabcontent">
        <property name="label">Content on notebook tab</property>
        </object>
      </child>
      <child type="tab">
        <object class="GtkLabel" id="tablabel">
          <property name="label">Tab label</property>
        </object>
        <packing>
          <property name="tab_expand">False</property>
          <property name="tab_fill">False</property>
        </packing>
      </child>
    </object>
  </child>
</object>    
See also:
2024-2-18
Accessor gtk:print-unix-dialog-current-page (object)
Syntax:
(gtk:print-unix-dialog-current-page object) => current-page
(setf (gtk:print-unix-dialog-current-page object) current-page)
Arguments:
object -- a gtk:print-unix-dialog widget
current-page -- an integer with the current page number
Details:
Accessor of the current-page slot of the gtk:print-unix-dialog class. The gtk:print-unix-dialog-current-page function gets the current page of the print dialog. The (setf gtk:print-unix-dialog-current-page) function sets the current page number. If current-page is not -1, this enables the current page choice for the range of pages to print.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-embed-page-setup (object)
Syntax:
(gtk:print-unix-dialog-embed-page-setup object) => embed
(setf (gtk:print-unix-dialog-embed-page-setup object) embed)
Arguments:
object -- a gtk:print-unix-dialog widget
embed -- a boolean whether embed page setup selection
Details:
Accessor of the embed-page-setup slot of the gtk:print-unix-dialog class. Embed page size combo box and orientation combo box into page setup page.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-has-selection (object)
Syntax:
(gtk:print-unix-dialog-has-selection object) => has-selection
(setf (gtk:print-unix-dialog-has-selection object) has-selection)
Arguments:
object -- a gtk:print-unix-dialog widget
has-selection -- true indicates that a selection exists
Details:
Accessor of the has-selection slot of the gtk:print-unix-dialog class. Whether the application has a selection.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-manual-capabilities (object)
Syntax:
(gtk:print-unix-dialog-manual-capabilities) => capabilities
(setf (gtk:print-unix-dialog-manual-capabilities object) capabilities)
Arguments:
object -- a gtk:print-unix-dialog widget
capabilities -- a gtk:print-capabilities value with the printing capabilities of the application
Details:
Accessor of the manual-capabilities slot of the gtk:print-unix-dialog class. This lets you specify the printing capabilities your application supports. For instance, if you can handle scaling the output then you pass the :scale value. If you do not pass that, then the dialog will only let you select the scale if the printing system automatically handles scaling.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-page-setup (object)
Syntax:
(gtk:print-unix-dialog-page-setup) => page-setup
(setf (gtk:print-unix-dialog-page-setup object) page-setup)
Arguments:
object -- a gtk:print-unix-dialog widget
page-setup -- a gtk:page-setup object
Details:
Accessor of the page-setup slot of the gtk:print-unix-dialog class. The gtk:print-unix-dialog-page-setup function gets the page setup that is used by the print dialog. The (setf gtk:print-unix-dialog-page-setup) function sets the page setup of the print dialog.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-print-settings (object)
Syntax:
(gtk:print-unix-dialog-print-settings object) => settings
(setf (gtk:print-unix-dialog-print-settings object) settings)
Arguments:
object -- a gtk:print-unix-dialog widget
settings -- a gtk:print-settings object
Details:
Accessor of the print-settings slot of the gtk:print-unix-dialog class. The gtk:print-unix-dialog-print-settings function gets the print settings that represents the current values in the print dialog. The (setf gtk:print-unix-dialog-print-settings) function sets the print settings for the print dialog.

Typically, this is used to restore saved print settings from a previous print operation before the print dialog is shown.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-selected-printer (object)
Syntax:
(gtk:print-unix-dialog-selected-printer object) => printer
Arguments:
object -- a gtk:print-unix-dialog widget
printer -- a gtk:printer object
Details:
Accessor of the selected-printer slot of the gtk:print-unix-dialog class. The gtk:print-unix-dialog-selected-printer function gets the currently selected printer.
See also:
2024-2-18
Accessor gtk:print-unix-dialog-support-selection (object)
Syntax:
(gtk:print-unix-dialog-support-selection) => selection
(setf (gtk:print-unix-dialog-support-selection object) selection)
Arguments:
object -- a gtk:print-unix-dialog widget
selection -- true to allow print selection
Details:
Accessor of the support-selection slot of the gtk:print-unix-dialog class. Whether the print dialog allows user to print a selection.
See also:
2024-2-18
Function gtk:print-unix-dialog-new (title parent)
Arguments:
title -- a string with the title of the dialog, or nil
parent -- a gtk:window widget with the transient parent of the dialog, or nil
Returns:
The new gtk:print-unix-dialog widget.
Details:
Creates a new print dialog.
See also:
2024-2-18
Function gtk:print-unix-dialog-settings (dialog)
Syntax:
(gtk:print-unix-dialog-settings object) => settings
(setf (gtk:print-unix-dialog-settings object) settings)
Arguments:
dialog -- a gtk:print-unix-dialog widget
settings -- a gtk:print-settings object
Details:
The gtk:print-unix-dialog-settings function gets the print settings that represents the current values in the print dialog. The (setf gtk:print-unix-dialog-settings) function sets the print settings for the print dialog.

Typically, this is used to restore saved print settings from a previous print operation before the print dialog is shown.
Notes:
The gtk:print-unix-dialog-settings function corresponds to the gtk:print-unix-dialog-print-settings function.
See also:
2024-2-18
Function gtk:print-unix-dialog-add-custom-tab (dialog child tab-label)
Arguments:
dialog -- a gtk:print-unix-dialog widget
child -- a gtk:widget object with the widget to put in the custom tab
tab-label -- a gtk:widget object to use as tab label
Details:
Adds a custom tab to the print dialog.
See also:
#2024-2-18
Function gtk:print-unix-dialog-page-setup-set (dialog)
Arguments:
dialog -- a gtk:print-unix-dialog widget
Returns:
The boolean whether a page setup was set by the user.
Details:
Gets whether a page setup was set by the user.
See also:
#2024-2-18

GtkPageSetupUnixDialog

Class gtk:page-setup-unix-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Details:
The page-setup-unix-dialog widget implements a page setup dialog for platforms which do not provide a native page setup dialog, like Unix.

Figure: GtkPageSetupUnixDialog

It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API.
Examples:
(defun create-page-setup-dialog (&optional parent)
  (let* ((path (sys-path "resource/page-setup.ini"))
         (pagesetup (gtk:page-setup-new))
         (dialog (gtk:page-setup-unix-dialog-new "Page Setup Dialog" parent)))
    ;; Connect a handler to the "response" signal
    (g:signal-connect dialog "response"
            (lambda (widget response)
              (when (= -5 response)
                (setf pagesetup
                      (gtk:page-setup-unix-dialog-page-setup dialog))
                (gtk:page-setup-to-file pagesetup path))
              (gtk:window-destroy widget)))
    ;; Load and set Page setup from file
    (if (gtk:page-setup-load-file pagesetup path)
        (format t "PAGE SETUP successfully loaded~%")
        (format t "PAGE SETUP cannot be loaded, use standard settings~%"))
    (setf (gtk:page-setup-unix-dialog-page-setup dialog) pagesetup)
    ;; Present dialog
    (gtk:window-present dialog)))    
See also:
2024-5-1
Function gtk:page-setup-unix-dialog-new (title parent)
Arguments:
title -- a string with the title of the dialog, or nil
parent -- a gtk:window transient parent of the dialog, or nil
Returns:
Details:
Creates a new page setup dialog.
See also:
2024-5-1
Function gtk:page-setup-unix-dialog-page-setup (dialog)
Syntax:
(gtk:page-setup-unix-dialog-page-setup dialog) => setup
(setf (gtk:page-setup-unix-dialog-page-setup dialog) setup)
Arguments:
dialog -- a gtk:page-setup-unix-dialog widget
setup -- a gtk:page-setup object
Details:
The gtk:page-setup-unix-dialog-page-setup function gets the currently selected page setup from the page setup dialog. The (setf gtk:page-setup-unix-dialog-page-setup) function sets the page setup from which the page setup dialog takes its values.
See also:
2024-1-5
Function gtk:page-setup-unix-dialog-print-settings (dialog)
Syntax:
(gtk:page-setup-unix-dialog-print-settings dialog) => settings
(setf (gtk:page-setup-unix-dialog-print-settings dialog) settings)
Arguments:
dialog -- a gtk:page-setup-unix-dialog widget
settings -- a gtk:print-settings object
Details:
The gtk:page-setup-unix-dialog-print-settings function gets the current print settings from the page setup dialog. The (setf gtk:page-setup-unix-dialog-print-settings) function sets the print settings from which the page setup dialog takes its values.
See also:
#2024-1-5

GtkPrintSetup

GBoxed gtk:print-setup
Declaration:
(glib:define-gboxed-opaque print-setup "GtkPrintSetup"
  :export t
  :type-initializer "gtk_print_setup_get_type"
  :alloc (error "GtkPrintSetup cannot be created from the Lisp side."))  
Details:
The gtk:print-setup structure is an auxiliary structure for printing that allows decoupling the setup from the printing. A print setup is obtained by calling the gtk:print-dialog-setup function, and can later be passed to print functions such as the gtk:print-dialog-print-file function.

Print setups can be reused for multiple print calls.

Applications may wish to store the page setup and print settings from the print setup and copy them to the print dialog if they want to keep using them.

Since 4.14
See also:
2024-11-10
Function gtk:print-setup-page-setup (setup)
Arguments:
setup -- a gtk:print-setup instance
Returns:
The gtk:page-setup instance, or nil.
Details:
Returns the page setup of setup. It may be different from the page setup of the gtk:print-dialog instance if the user changed it during the setup process.

Since 4.14
See also:
#2024-11-10
Function gtk:print-setup-print-settings (setup)
Arguments:
setup -- a gtk:print-setup instance
Returns:
The gtk:print-settings instance, or nil.
Details:
Returns the print settings of setup. They may be different from the print settings of the gtk:print-dialog object if the user changed them during the setup process.

Since 4.14
See also:
#2024-11-10

GtkPrintDialog

Class gtk:print-dialog
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accept-label
The accept-label property of type :string (Read / Write)
The label that may be shown on the accept button of a print dialog.
Default value: nil
modal
The modal property of type :boolean (Read / Write)
Whether the print dialog is modal.
Default value: true
page-setup
The page-setup property of type gtk:page-setup (Read / Write)
The page setup to use.
print-settings
The print-settings property of type gtk:print-settings (Read / Write)
The print settings to use.
title
The title property of type :string (Read / Write)
The title that may be shown on the print dialog.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:print-dialog object collects the arguments that are needed to present a print dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the gtk:print-dialog-setup function. The actual printing can be done with the gtk:print-dialog-print-file function. These APIs follows the GIO async pattern, and the results can be obtained by calling the corresponding finish methods.

Since 4.14
See also:
2024-11-10
Accessor gtk:print-dialog-accept-label (object)
Syntax:
(gtk:print-dialog-accecpt-label object) => label
(setf (gtk:print-dialog-accept-label object) label)
Arguments:
object -- a gtk:print-dialog object
label -- a string with the accept label
Details:
Accessor of the accept-label slot of the gtk:print-dialog class. The gtk:print-dialog-accept-label function returns the label that will be shown on the accept button of the print dialog. The (setf gtk:print-dialog-accept-label) function sets the label.

Since 4.14
See also:
2024-11-10
Accessor gtk:print-dialog-modal (object)
Syntax:
(gtk:print-dialog-modal object) => setting
(setf (gtk:print-dialog-modal object) setting)
Arguments:
object -- a gtk:print-dialog object
setting -- a boolean whether the print dialog is modal
Details:
Accessor of the modal slot of the gtk:print-dialog class. The gtk:print-dialog-modal function returns whether the print dialog blocks interaction with the parent window while it is presented. The (setf gtk:print-dialog-modal) sets the property.

Since 4.14
See also:
2024-11-10
Accessor gtk:print-dialog-page-setup (object)
Syntax:
(gtk:print-dialog-page-setup object) => setup
(setf (gtk:print-dialog-page-setup object) setup)
Arguments:
object -- a gtk:print-dialog object
setup -- a gtk:page-setup object
Details:
Accessor of the page-setup slot of the gtk:print-dialog class. The gtk:print-dialog-page-setup function gets the page setup for the print dialog. The (setf gtk:print-dialog-page-setup) function sets the page setup.

Since 4.14
See also:
2024-11-10
Accessor gtk:print-dialog-print-settings (object)
Syntax:
(gtk:print-dialog-print-settings object) => settings
(setf (gtk:print-dialog-print-settings object) settings)
Arguments:
object -- a gtk:print-dialog object
settings -- a gtk:print-settings object
Details:
Accessor of the print-settings slot of the gtk:print-dialog class. The gtk:print-dialog-print-settings function returns the print settings for the print dialog. The (setf gtk:print-dialog-print-settings) function sets the print settings.

Since 4.14
See also:
2024-11-10
Accessor gtk:print-dialog-title (object)
Syntax:
(gtk:print-dialog-title object) => title
(setf (gtk:print-dialog-title object) title)
Arguments:
object -- a gtk:print-dialog object
title -- a gtk:print-settings object
Details:
Accessor of the title slot of the gtk:print-dialog class. The gtk:print-dialog-title function returns the title that will be shown on the print dialog. The (setf gtk:print-dialog-title) function sets the title.

Since 4.14
See also:
2024-11-10
Function gtk:print-dialog-new ()
Returns:
The new gtk:print-dialog object.
Details:
Creates a new print dialog.

Since 4.14
See also:
2024-11-10
Function gtk:print-dialog-print-file (dialog parent setup file cancellable func)
Arguments:
dialog -- a gtk:print-dialog object
parent -- a parent gtk:window widget
setup -- a gtk:print-setup instance to use
file -- a g:file object to print
cancellable -- a g:cancellable instance to cancel the operation
func -- a g:async-ready-callback callback funtion to call when the operation is complete
Details:
The gtk:print-dialog-print-file function prints a file. If you pass nil as print setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction.

This method completes asynchronously. Use the gtk:print-dialog-print-file-finish function inside the g:async-ready-callback callback function to obtain the result of the operation.

Since 4.14
See also:
#2024-11-10
Function gtk:print-dialog-print-file-finish (dialog result)
Arguments:
dialog -- a gtk:print-dialog object
result -- a g:async-result instance
Returns:
The boolean whether the call was successful.
Details:
Finishes the gtk:print-dialog-print-file function call and returns the results.

Since 4.14
See also:
#2024-11-10
Function gtk:print-dialog-setup (dialog parent cancellable func)
Arguments:
dialog -- a gtk:print-dialog object
parent -- a parent gtk:window widget
cancellable -- a g:cancellable instance to cancel the operation
func -- a g:async-ready-callback callback funtion to call when the operation is complete
Details:
The gtk:print-dialog-setup function presents a print dialog to let the user select a printer, and set up print settings and page setup. The callback will be called when the dialog is dismissed. The obtained gtk:print-setup instance can then be passed to the gtk:print-dialog-print-file function.

One possible use for this method is to have the user select a printer, then show a page setup UI in the application, for example, to arrange images on a page, then call the gtk:print-dialog-print-file function on dialog to do the printing without further user interaction.

This method completes asynchronously. Use the gtk:print-dialog-setup-finish function inside the g:async-ready-callback callback function to obtain the result of the operation.

Since 4.14
See also:
#2024-11-10
Function gtk:print-dialog-setup-finish (dialog result)
Arguments:
dialog -- a gtk:print-dialog object
result -- a g:async-result instance
Returns:
The gtk:print-setup instance that resulted from the call, or nil if the call was not successful.
Details:
Finishes the gtk:print-dialog-setup function call. If the call was successful, it returns a gtk:print-setup instance which contains the print settings and page setup information that will be used to print.

Since 4.14
See also:
#2024-11-10

Shortcuts Overview

GtkShortcutsWindow

Class gtk:shortcuts-window
Superclasses:
Documented Subclasses:
None
Direct Slots:
section-name
The section-name property of type :string (Read / Write)
The name of the section to show. This should be the section name of one of the gtk:shortcuts-section objects that are in this shortcuts window.
Default value: "internal-search"
view-name
The view-name property of type :string (Read / Write)
The view name by which to filter the contents. This should correspond to the view property of some of the gtk:shortcuts-group objects that are inside this shortcuts window. Set this to nil to show all groups.
Default value: nil
Slot Access Functions:
Details:
The gtk:shortcuts-window widget shows brief information about the keyboard shortcuts and gestures of an application. The shortcuts can be grouped, and you can have multiple sections in this window, corresponding to the major modes of your application.

Additionally, the shortcuts can be filtered by the current view, to avoid showing information that is not relevant in the current application context.

The recommended way to construct a shortcuts window is with a gtk:builder UI definition, by populating a shortcuts window with one or more gtk:shortcuts-section objects, which contain gtk:shortcuts-group objects that in turn contain objects of the gtk:shortcuts-shortcut class.
Examples:
A simple example: This example has as single section. As you can see, the shortcut groups are arranged in columns, and spread across several pages if there are too many to find on a single page. The .ui file for this example can be found here.

Figure: GEdit shortcuts

An example with multiple views: This example shows a shortcuts window that has been configured to show only the shortcuts relevant to the "stopwatch" view. The .ui file for this example can be found here.

Figure: Clock shortcuts

An example with multiple sections: This example shows a shortcuts window with two sections, "Editor Shortcuts" and "Terminal Shortcuts". The .ui file for this example can be found here.

Figure: Builder shortcuts
Signal Details:
The "close" signal
lambda (shortcutswindow)    :action      
shortcutswindow
The gtk:shortcuts-window object.
The signal is a keybinding signal which gets emitted when the user uses a keybinding to close the window. The default binding for this signal is the Escape key.
The "search" signal
lambda (shortcutswindow)    :action      
shortcutswindow
The gtk:shortcuts-window object.
The signal is a keybinding signal which gets emitted when the user uses a keybinding to start a search. The default binding for this signal is the Control-F key.
See also:
2024-2-18
Accessor gtk:shortcuts-window-section-name (object)
Syntax:
(gtk:shortcuts-window-section-name object) => name
(setf (gtk:shortcuts-window-section-name object) name)
Arguments:
object -- a gtk:shortcuts-window widget
name -- a string with a name of the section to show
Details:
Accessor of the section-name slot of the gtk:shortcuts-window class. The name of the section to show. This should be the section name of one of the gtk:shortcuts-section objects that are in this shortcuts window.
See also:
2024-2-18
Accessor gtk:shortcuts-window-view-name (object)
Syntax:
(gtk:shortcuts-window-view-name object) => name
(setf (gtk:shortcuts-window-view-name object) name)
Arguments:
object -- a gtk:shortcuts-window widget
name -- a string with the view name by which to filter the contents
Details:
Accessor of the view-name slot of the gtk:shortcuts-window class. The view name by which to filter the contents. This should correspond to the view property of some of the gtk:shortcuts-group objects that are inside this shortcuts window. Set this to nil to show all groups.
See also:
2024-2-18
Function gtk:shortcuts-window-add-section (window section)
Arguments:
window -- a gtk:shortcuts-window widget
section -- a gtk:shortcuts-section widget to add
Details:
Adds a section to the shortcuts window. This is the programmatic equivalent to using a gtk:builder UI definition and a <child> tag to add the child. Using the gtk:window-child function is not appropriate as the shortcuts window manages its children internally.

Since 4.14
See also:
#2024-10-27

GtkShortcutsSection

Class gtk:shortcuts-section
Superclasses:
Documented Subclasses:
None
Direct Slots:
max-height
The max-heigth property of type :uint (Read / Write)
The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in for most cases.
Default value: 15
section-name
The section-name property of type :string (Read / Write)
A unique name to identify this section among the sections added to the gtk:shortcuts-window widget. Setting the section-name property to this string will make this section shown in the gtk:shortcuts-window widget.
Default value: nil
title
The title property of type :string (Read / Write)
The string to show in the section selector of the gtk:shortcuts-window widget for this section. If there is only one section, you do not need to set a title, since the section selector will not be shown in this case.
Default value: nil
view-name
The view-name property of type :string (Read / Write)
A view name to filter the groups in this section by. See the view property. Applications are expected to use the view-name property for this purpose.
Default value: nil
Slot Access Functions:
Details:
A gtk:shortcuts-section widget collects all the keyboard shortcuts and gestures for a major application mode. If your application needs multiple sections, you should give each section a unique section name and a title that can be shown in the section selector of the gtk:shortcuts-window widget.

The max-height property can be used to influence how the groups in the section are distributed over pages and columns.

This widget is only meant to be used with gtk:shortcuts-window widgets.
Signal Details:
The "change-current-page" signal
lambda (section arg)    :action      
section
The gtk:shortcuts-section widget.
arg
An integer, no description available.
2024-2-18
Accessor gtk:shortcuts-section-max-height (object)
Syntax:
(gtk:shortcuts-section-max-height object) => height
(setf (gtk:shortcuts-section-max-height object) height)
Arguments:
object -- a gtk:shortcuts-section widget
height -- an unsigned with the maximum number of lines to allow per column
Details:
Accessor of the max-height slot of the gtk:shortcuts-section class. The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in for most cases.
See also:
2024-2-18
Accessor gtk:shortcuts-section-section-name (object)
Syntax:
(gtk:shortcuts-section-section-name object) => name
(setf (gtk:shortcuts-section-section-name object) name)
Arguments:
object -- a gtk:shortcuts-section widget
name -- a string with a unique name to identify this section
Details:
Accessor of the section-name slot of the gtk:shortcuts-section class. A unique name to identify this section among the sections added to the gtk:shortcuts-window widget. Setting the section-name property to this string will make this section shown in the gtk:shortcuts-window widget.
See also:
2024-2-18
Accessor gtk:shortcuts-section-title (object)
Syntax:
(gtk:shortcuts-section-title object) => title
(setf (gtk:shortcuts-section-title object) title)
Arguments:
object -- a gtk:shortcuts-section widget
title -- a string to show in the section selector
Details:
Accessor of the title slot of the gtk:shortcuts-section class. The string to show in the section selector of the gtk:shortcuts-window widget for this section. If there is only one section, you do not need to set a title, since the section selector will not be shown in this case.
See also:
2024-2-18
Accessor gtk:shortcuts-section-view-name (object)
Syntax:
(gtk:shortcuts-section-view-name object) => name
(setf (gtk:shortcuts-section-view-name object) name)
Arguments:
object -- a gtk:shortcuts-section widget
name -- a string with a view name to filter the groups in this section by
Details:
Accessor of the view-name slot of the gtk:shortcuts-section class. A view name to filter the groups in this section by. See the view property. Applications are expected to use the view-name property for this purpose.
See also:
2024-5-22
Function gtk:shortcuts-section-add-group (section group)
Arguments:
section -- a gtk:shortcuts-section widget
group -- a gtk:shortcuts-group widget to add
Details:
Adds a group to the shortcuts section. This is the programmatic equivalent to using a gtk:builder UI definition and a <child> tag to add the child. Adding children with the gtk:box API is not appropriate, as the gtk:shortcuts-section widget manages its children internally.

Since 4.14
See also:
#2024-10-27

GtkShortcutsGroup

Class gtk:shortcuts-group
Superclasses:
Documented Subclasses:
None
Direct Slots:
accel-size-group
The accel-size-group property of type gtk:size-group (Write)
The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications.
height
The height property of type :uint (Read)
A rough measure for the number of lines in this group. This is used internally by GTK, and is not useful for applications.
Default value: 1
title
The title property of type :string (Read / Write)
The title for this group of shortcuts.
Default value: ""
title-size-group
The title-size-group property of type gtk:size-group (Write)
The size group for the textual portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications.
view
The view property of type :string (Read / Write)
An optional view that the shortcuts in this group are relevant for. The group will be hidden if the view-name property does not match the view of this group. Set this to nil to make the group always visible.
Default value: nil
Slot Access Functions:
Details:
The gtk:shortcuts-group widget represents a group of related keyboard shortcuts or gestures. The group has a title. It may optionally be associated with a view of the application, which can be used to show only relevant shortcuts depending on the application context.

This widget is only meant to be used with the gtk:shortcuts-window widget.
See also:
2024-10-27
Accessor gtk:shortcuts-group-accel-size-group (object)
Syntax:
(gtk:shortcuts-group-accel-size-group object) => size-group
(setf (gtk:shortcuts-group-accel-size-group object) size-group)
Arguments:
object -- a gtk:shortcuts-group widget
size-group -- a gtk:size-group object
Details:
Accessor of the accel-size-group slot of the gtk:shortcuts-group class. The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications.
See also:
2024-10-27
Accessor gtk:shortcuts-group-height (object)
Syntax:
(gtk:shortcuts-group-height object) => height
(setf (gtk:shortcuts-group-height object) height)
Arguments:
object -- a gtk:shortcuts-group widget
height -- an unsigned integer with the measure for the number of lines
Details:
Accessor of the height slot of the gtk:shortcuts-group class. A rough measure for the number of lines in this group. This is used internally by GTK, and is not useful for applications.
See also:
2024-10-27
Accessor gtk:shortcuts-group-title (object)
Syntax:
(gtk:shortcuts-group-title object) => title
(setf (gtk:shortcuts-group-title object) title)
Arguments:
object -- a gtk:shortcuts-group widget
title -- a string with the title for this group of shortcuts
Details:
Accessor of the title slot of the gtk:shortcuts-group class. The title for this group of shortcuts.
See also:
2024-10-27
Accessor gtk:shortcuts-group-title-size-group (object)
Syntax:
(gtk:shortcuts-group-title-size-group object) => size-group
(setf (gtk:shortcuts-group-title-size-group object) size-group)
Arguments:
object -- a gtk:shortcuts-group widget
title -- a gtk:size-group object
Details:
Accessor of the title-size-group slot of the gtk:shortcuts-group class. The size group for the textual portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications.
See also:
2024-10-27
Accessor gtk:shortcuts-group-view (object)
Syntax:
(gtk:shortcuts-group-view object) => view
(setf (gtk:shortcuts-group-view object) view)
Arguments:
object -- a gtk:shortcuts-group widget
view -- a string with an optional view
Details:
Accessor of the view slot of the gtk:shortcuts-group class. An optional view that the shortcuts in this group are relevant for. The group will be hidden if the view-name property does not match the view of this group. Set this to nil to make the group always visible.
See also:
2024-10-27
Function gtk:shortcuts-group-add-shortcut (group shortcut)
Arguments:
group -- a gtk:shortcuts-group widget
shortcut -- a gtk:shortcuts-shortcut widget
Details:
Adds a shortcut to the shortcuts group. This is the programmatic equivalent to using a gtk:builder UI definition and a <child> tag to add the child. Adding children with other API is not appropriate as the gtk:shortcuts-group widget manages its children internally.

Since 4.14
See also:
gtk:shortcuts-group
gtk:shortctus-shortcut
#2024-10-27

GtkShortcutsShortcut

GEnum gtk:shortcut-type
Declaration:
(gobject:define-genum "GtkShortcutType" gtk:shortcut-type
  (:export t
   :type-initializer "gtk_shortcut_type_get_type")
  :accelerator
  :gesture-pinch
  :gesture-stretch
  :gesture-rotate-clockwise
  :gesture-rotate-conterclockwise
  :gesture-two-finger-swipe-left
  :gesture-two-finger-swipe-right
  :gesture
  :gesture-swipe-left
  :gesture-swipe-right)  
Values:
:accelerator
The shortcut is a keyboard accelerator. The accelerator property will be used.
:gesture-pinch
The shortcut is a pinch gesture. GTK provides an icon and subtitle.
:gesture-stretch
The shortcut is a stretch gesture. GTK provides an icon and subtitle.
:gesture-rotate-clockwise
The shortcut is a clockwise rotation gesture. GTK provides an icon and subtitle.
:gesture-rotate-counter-clockwise
The shortcut is a counterclockwise rotation gesture. GTK provides an icon and subtitle.
:gesture-two-finger-swipe-left
The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle.
:gesture-two-finger-swipe-right
The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle.
:gesture
The shortcut is a gesture. The icon property will be used.
:gesture-swipe-left
The shortcut is a swipe gesture. GTK provides an icon and subtitle.
:gesture-swipe-right
The shortcut is a swipe gesture. GTK provides an icon and subtitle.
Details:
The gtk:shortcut-type enumeration specifies the kind of shortcut that is being described.
See also:
2024-2-18
Class gtk:shortcuts-shortcut
Superclasses:
Documented Subclasses:
None
Direct Slots:
accel-size-group
The accel-size-group property of type gtk:size-group (Write)
The size group for the accelerator portion of this shortcut. This is used internally by GTK, and must not be modified by applications.
accelerator
The accelerator property of type :string (Read / Write)
The accelerator(s) represented by this object. This property is used if the shortcut-type property is set to the :accelerator value. The syntax of this property is an extension of the syntax understood by the gtk:accelerator-parse function. Multiple accelerators can be specified by separating them with a space, but keep in mind that the available width is limited. It is also possible to specify ranges of shortcuts, using ... between the keys. Sequences of keys can be specified using a + or & between the keys.
Default value: nil
action-name
The action-name property of type :string (Read / Write)
A detailed action name. If this is set for a shortcut of type :accelerator, then GTK will use the accelerators that are associated with the action via the gtk:application-accels-for-action function, and setting the accelerator property is not necessary.
Default value: nil
direction
The direction property of type gtk:text-direction (Read / Write)
The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to :none.
Default value: :dir-none
icon
The icon property of type g:icon (Read / Write)
An icon to represent the shortcut or gesture. This property is used if the shortcut-type property is set to the :gesture value. For the other predefined gesture types, GTK provides an icon on its own.
icon-set
The icon-set property of type :boolean (Read / Write)
True if an icon has been set.
Default value: false
shortcut-type
The shortcut-type property of type gtk:shortcut-type (Read / Write)
The type of shortcut that is represented.
Default value: :accelerator
subtitle
The subtitle property of type :string (Read / Write)
The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK provides a subtitle on its own.
Default value: ""
subtitle-set
The subtitle-set property of type :boolean (Read / Write)
True if a subtitle has been set.
Default value: false
title
The title property of type :string (Read / Write)
The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line.
Default value: ""
title-size-group
The title-size-group property of type gtk:size-group (Write)
The size group for the textual portion of this shortcut. This is used internally by GTK, and must not be modified by applications.
Slot Access Functions:
Details:
A gtk:shortcuts-shortcut widget represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with the gtk:shortcuts-window widget.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-accel-size-group (object)
Syntax:
(gtk:shortcuts-shortcut-accel-size-group object) => group
(setf (gtk:shortcuts-shortcut-accel-size-group object) group)
Arguments:
object -- a gtk:shortcuts-shortcut widget
group -- a gtk:size-group object
Details:
Accessor of the accel-size-group slot of the gtk:shortcuts-shortcut class. The size group for the accelerator portion of this shortcut. This is used internally by GTK, and must not be modified by applications.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-accelerator (object)
Syntax:
(gtk:shortcuts-shortcut-accelerator object) => accelerator
(setf (gtk:shortcuts-shortcut-accelerator object) accelerator)
Arguments:
object -- a gtk:shortcuts-shortcut widget
accelerator -- a string with the accelerator
Details:
Accessor of the accelerator slot of the gtk:shortcuts-shortcut class. The accelerator(s) represented by this object. This property is used if the shortcut-type property is set to the :accelerator value. The syntax of this property is an extension of the syntax understood by the gtk:accelerator-parse function. Multiple accelerators can be specified by separating them with a space, but keep in mind that the available width is limited. It is also possible to specify ranges of shortcuts, using ... between the keys. Sequences of keys can be specified using a + or & between the keys.
Examples:
A single shortcut: <ctl><alt>delete
Two alternative shortcuts: <shift>a Home
A range of shortcuts: <alt>1...<alt>9
Several keys pressed together: Control_L&Control_R
A sequence of shortcuts or keys: <ctl>c+<ctl>x
Use + instead of & when the keys may or have to be pressed sequentially, e.g use t+t for 'press the t key twice'.
Note that <, > and & need to be escaped as <, > and & when used in .ui files.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-action-name (object)
Syntax:
(gtk:shortcuts-shortcut-action-name object) => name
(setf (gtk:shortcuts-shortcut-action-name object) name)
Arguments:
object -- a gtk:shortcuts-shortcut widget
name -- a string with the detailed action name
Details:
Accessor of the action-name slot of the gtk:shortcuts-shortcut class. A detailed action name. If this is set for a shortcut of type :accelerator, then GTK will use the accelerators that are associated with the action via the gtk:application-accels-for-action function, and setting the accelerator property is not necessary.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-direction (object)
Syntax:
(gtk:shortcuts-shortcut-direction object) => direction
(setf (gtk:shortcuts-shortcut-direction object) direction)
Arguments:
object -- a gtk:shortcuts-shortcut widget
direction -- a gtk:text-direction value
Details:
Accessor of the direction slot of the gtk:shortcuts-shortcut class. The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to the :none value.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-icon (object)
Syntax:
(gtk:shortcuts-shortcut-icon object) => icon
(setf (gtk:shortcuts-shortcut-icon object) icon)
Arguments:
object -- a gtk:shortcuts-shortcut widget
icon -- a g:icon object
Details:
Accessor of the icon slot of the gtk:shortcuts-shortcut class. An icon to represent the shortcut or gesture. This property is used if the shortcut-type property is set to the :gesture value. For the other predefined gesture types, GTK provides an icon on its own.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-icon-set (object)
Syntax:
(gtk:shortcuts-shortcut-icon-set object) => setting
(setf (gtk:shortcuts-shortcut-icon-set object) setting)
Arguments:
object -- a gtk:shortcuts-shortcut widget
setting -- a boolean whether an icon has been set
Details:
Accessor of the icon-set slot of the gtk:shortcuts-shortcut class. True if an icon has been set.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-shortcut-type (object)
Syntax:
(gtk:shortcuts-shortcut-shortcut-type object) => type
(setf (gtk:shortcuts-shortcut-shortcut-type object) type)
Arguments:
object -- a gtk:shortcuts-shortcut widget
type -- a gtk:shortcut-type value
Details:
Accessor of the shortcut-type slot of the gtk:shortcuts-shortcut class. The type of shortcut that is represented.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-subtitle (object)
Syntax:
(gtk:shortcuts-shortcut-subtitle object) => subtitle
(setf (gtk:shortcuts-shortcut-subtitle object) subtitle)
Arguments:
object -- a gtk:shortcuts-shortcut widget
subtitle -- a string with the subtitle for the shortcut
Details:
Accessor of the subtitle slot of the gtk:shortcuts-shortcut class. The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK provides a subtitle on its own.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-subtitle-set (object)
Syntax:
(gtk:shortcuts-shortcut-subtitle-set object) => setting
(setf (gtk:shortcuts-shortcut-subtitle-set object) setting)
Arguments:
object -- a gtk:shortcuts-shortcut widget
setting -- a boolean whether a subtitle has been set
Details:
Accessor of the subtitle-set slot of the gtk:shortcuts-shortcut class. True if a subtitle has been set.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-title (object)
Syntax:
(gtk:shortcuts-shortcut-title object) => title
(setf (gtk:shortcuts-shortcut-title object) title)
Arguments:
object -- a gtk:shortcuts-shortcut widget
title -- a string with the textual description for the shortcut
Details:
Accessor of the title slot of the gtk:shortcuts-shortcut class. The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line.
See also:
2024-2-18
Accessor gtk:shortcuts-shortcut-title-size-group (object)
Syntax:
(gtk:shortcuts-shortcut-title-size-group object) => group
(setf (gtk:shortcuts-shortcut-title-size-group object) group)
Arguments:
object -- a gtk:shortcuts-shortcut widget
group -- a gtk:size-group object
Details:
Accessor of the title-size-group slot of the gtk:shortcuts-shortcut class. The size group for the textual portion of this shortcut. This is used internally by GTK, and must not be modified by applications.
See also:
2024-5-22

GtkShortcutLabel

Class gtk:shortcut-label
Superclasses:
Documented Subclasses:
None
Direct Slots:
accelerator
The accelerator property of type :string (Read / Write)
The accelerator that the shortcut label displays. See the accelerator property for the accepted syntax.
Default value: nil
disabled-text
The disabled-text property of type :string (Read / Write)
The text that is displayed when no accelerator is set.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:shortcut-label widget is a widget that represents a single keyboard shortcut or gesture in the user interface.
See also:
2024-10-27
Accessor gtk:shortcut-label-accelerator (object)
Syntax:
(gtk:shortcut-label-accelerator object) => accelerator
(setf (gtk:shortcut-label-accelerator object) accelerator)
Arguments:
object -- a gtk:shortcut-label widget
accelerator -- a string with the accelerator
Details:
Accessor of the accelerator slot of the gtk:shortcut-label class. The gtk:shortcut-label-accelerator function retrieves the current accelerator of the shortcut label. The (setf gtk:shortcut-label-accelerator) function sets the accelerator.
See also:
2024-10-27
Accessor gtk:shortcut-label-disabled-text (object)
Syntax:
(gtk:shortcut-label- object) => disabled-text
(setf (gtk:shortcut-label-accelerator object) disabled-text)
Arguments:
object -- a gtk:shortcut-label widget
accelerator -- a string with text to be displayed when no accelerator is set
Details:
Accessor of the accelerator slot of the gtk:shortcut-label class. The gtk:shortcut-label-disabled-text function retrieves the text that is displayed when no accelerator is set. The (setf gtk:shortcut-label-disabled-text) function sets the text.
See also:
2024-10-27
Function gtk:shortcut-label-new (accelerator)
Arguments:
accelerator -- a string with the initial accelerator
Returns:
The newly gtk:shortcut-label widget.
Details:
Creates a new shortcut label with accelerator set.
See also:
2024-10-27

Accessibility

GtkAccessibleRange

Interface gtk:accessible-range
Superclasses:
gtk:accessible, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:accessible-range interface describes ranged controls, for example, controls which have a single value within an allowed range and that can optionally be changed by the user. The interface is expected to be implemented by controls using the following roles of the gtk:accessible-role enumeration:
  • :meter
  • :progress-bar
  • :scrollbar
  • :slider
  • :spin-button
If that is not the case, a warning will be issued at run time.

In addition to this interface, its implementors are expected to provide the correct values for the following properties of the gtk:accessible-property enumeration:
  • :value-max
  • :value-min
  • :value-now
  • :value-text
Since 4.10
See also:
2024-11-5

GtkAccessibleText

GEnum gtk:accessible-text-content-change
Declaration:
(gobject:define-genum "GtkAccessibleTextContentChange"
                      accessible-text-content-change
  (:export t
   :type-initializer "gtk_accessible_text_content_change_get_type")
  (:insert 0)
  (:remove 1))  
Values:
:insert
Contents change as the result of an insert operation.
:remvve
Contents change as the result of a remove operation.
Details:
The type of contents change operation. Since 4.14
See also:
2024-11-5
GEnum gtk:accessible-text-granularity
Declaration:
(gobject:define-genum "GtkAccessibleTextGranularity" accessible-text-granularity
  (:export t
   :type-initializer "gtk_accessible_text_granularity_get_type")
  (:character 0)
  (:word 1)
  (:sentence 2)
  (:line 3)
  (:paragraph 4))  
Values:
:character
Use the boundary between characters, including non-printing characters.
:word
Use the boundary between words, starting from the beginning of the current word and ending at the beginning of the next word.
:sentence
Use the boundary between sentences, starting from the beginning of the current sentence and ending at the beginning of the next sentence.
:line
Use the boundary between lines, starting from the beginning of the current line and ending at the beginning of the next line.
:paragraph
Use the boundary between paragraphs, starting from the beginning of the current paragraph and ending at the beginning of the next paragraph.
Details:
The granularity for queries about the text contents of a gtk:accessible-text implementation. Since 4.14
See also:
2024-11-5
Interface gtk:accessible-text
Superclasses:
gtk:accessible, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
An interface for accessible objects containing formatted text. The gtk:accessible-text interfaces is meant to be implemented by accessible objects that have text formatted with attributes, or non-trivial text contents.

You should use the :label or the :description values of the gtk:accessible-property enumeration for accessible objects containing simple, unformatted text.

Since 4.14
See also:
2024-5-26
Function gtk:accessible-text-caret-position (accessible)
Arguments:
accessible -- a gtk:accessible-text object
Returns:
The unsigned integer with the position of the caret, in characters.
Details:
Retrieves the position of the caret inside the accessible object. Since 4.14
See also:
#2024-11-5
Function gtk:accessible-text-contents (accessible start end)
Arguments:
accessible -- a gtk:accessible-text object
start -- an unsigned integer with the beginning of the range, in characters
end -- an unsigned integer with the end of the range, in characters
Returns:
The g:bytes instance with the requested slice of the contents of the accessible object, as UTF-8.
Details:
Retrieve the current contents of the accessible object within the given range. If end is G_MAXUINT, the end of the range is the full content of the accessible object.

Since 4.14
See also:
#2024-11-5
Function gtk:accessible-text-contents-at (accessible offset granularity)
Syntax:
(gtk:accessible-text-contents-at accessible offset granularity) => start, end
Arguments:
accessible -- a gtk:accessible-text object
offset -- an unsigned integer with the offset, in characters
granularity -- a gtk:accessible-text-granularity value
Returns:
start -- an unsigned integer with the start of the range, in characters
end -- an unsigned integer with the end of the range, in characters
Details:
Retrieve the current contents of the accessible object starting from the given offset, and using the given granularity. The start and end values contain the boundaries of the text.

Since 4.14
See also:
#2024-11-5
Function gtk:accessible-text-extents (accessible start end extents)
Arguments:
accessible -- a gtk:accessible-text object
start -- an unsigned integer with the start offset, in characters
end -- an unsigned integer with the end offset, in characters,
extents -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance if the extents were filled, nil otherwise.
Details:
Obtains the extents of a range of text, in widget coordinates.

Since 4.16
See also:
#2024-11-5
Function gtk:accessible-text-offset (accessible point)
Arguments:
accessible -- a gtk:accessible-text object
point -- a graphene:point-t instance
Returns:
The unsigned integer with the offset, if set, otherwise nil.
Details:
Gets the text offset at a given point. Since 4.16
See also:
#2024-11-5
Function gtk:accessible-text-update-caret-position (accessible)
Arguments:
accessible -- a gtk:accessible-text object
Details:
Updates the position of the caret. Implementations of the gtk:accessible-text interface should call this function every time the caret has moved, in order to notify assistive technologies.

Since 4.14
See also:
#2024-11-5
Function gtk:accessible-text-update-contents (accessible change start end)
Arguments:
accessible -- a gtk:accessible-text object
change -- a gtk:accessible-text-content-change value with the type of change in the contents
start -- an unsigned integer with the start offset, in characters
end -- an unsigned integer with the end offset, in characters
Details:
Notifies assistive technologies of a change in contents. Implementations of the gtk:accessible-text interface should call this function every time their contents change as the result of an operation, like an insertion or a removal.
Notes:
If the change is a deletion, this function must be called before removing the contents, if it is an insertion, it must be called after inserting the new contents.
Since 4.14
See also:
#2024-11-5
Function gtk:accessible-text-update-selection-bound (accessible)
Arguments:
accessible -- a gtk:accessible-text object
Details:
Updates the boundary of the selection. Implementations of the gtk:accessible-text interface should call this function every time the selection has moved, in order to notify assistive technologies.

Since 4.14
See also:
#2024-11-5

GtkAccessibleList

GBoxed gtk:accessible-list
Declaration:
(glib:define-gboxed-opaque accessible-list "GtkAccessibleList"
  :export t
  :type-initializer "gtk_accessible_list_get_type"
  :alloc (error "GtkAccessibleList cannot be created from the Lisp side."))  
Details:
A boxed type which wraps a list of references to gtk:accessible objects.

Since 4.14 gtk:accessible-list-new-from-list
See also:
2024-11-5
Function gtk:accessible-list-new-from-list (list)
Arguments:
list -- a list of gtk:accessible objects
Returns:
The new gtk:accessible-list instance.
Details:
Allocates a new gtk:accessible-list instance, doing a shallow copy of the passed list of gtk:accessible objects.

Since 4.14
See also:
2024-11-5
Function gtk:accessible-list-objects (list)
Arguments:
list -- a gtk:accessible-list instance
Returns:
The list of g:object instances.
Details:
Gets the list of objects this boxed type holds.

Since 4.14
See also:
2024-11-5

GtkAccessible

GEnum gtk:accessible-role
Declaration:
(gobject:define-genum "GtkAccessibleRole" accessible-role
  (:export t
   :type-initializer "gtk_accessible_role_get_type")
  :alert
  :alert-dialog
  :banner
  :button
  :caption
  :cell
  :checkbox
  :column-header
  :combo-box
  :command
  :composite
  :dialog
  :document
  :feed
  :form
  :generic
  :grid
  :grid-cell
  :group
  :heading
  :img
  :input
  :label
  :landmark
  :legend
  :link
  :list
  :list-box
  :list-item
  :log
  :main
  :marquee
  :math
  :meter
  :menu
  :menu-bar
  :menu-item
  :menu-item-checkbox
  :menu-item-radio
  :navigation
  :none
  :note
  :option
  :presentation
  :progress-bar
  :radio
  :radio-group
  :range
  :region
  :row
  :row-group
  :row-header
  :scrollbar
  :search
  :search-box
  :section
  :section-head
  :select
  :separator
  :slider
  :spin-button
  :status
  :structure
  :switch
  :tab
  :table
  :tab-list
  :tab-panel
  :text-box
  :time
  :timer
  :toolbar
  :tooltip
  :tree
  :tree-grid
  :tree-item
  :widget
  :window
  #+gtk-4-10
  :toggle-button
  #+gtk-4-12
  :application
  #+gtk-4-14
  :paragraph
  #+gtk-4-14
  :block-quote
  #+gtk-4-14
  :article
  #+gtk-4-14
  :comment
  #+gtk-4-14
  :terminal)  
Values:
:alert
An element with important, and usually time-sensitive, information.
:alert-dialog
A type of dialog that contains an alert message.
:banner
Unused
:button
An input element that allows for user-triggered actions when clicked or pressed.
:caption
Unused
:cell
Unused
:checkbox
A checkable input element that has three possible values: "true", "false", or "mixed".
:column-header
A header in a columned list.
:combo-box
An input that controls another element, such as a list or a grid, that can dynamically pop up to help the user set the value of the input.
:command
Abstract role.
:composite
Abstract role.
:dialog
A dialog is a window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response.
:document
Unused
:feed
Unused
:form
Unused
:generic
Unused
:grid
A grid of items.
:grid-cell
An item in a grid or tree grid.
:group
An element that groups multiple widgets. GTK uses this role for various containers, like the gtk:box, gtk:viewport, and gtk:header-bar widgets.
:heading
Unused
:img
An image.
:input
Abstract role.
:label
A visible name or caption for a user interface component.
:landmark
Abstract role.
:legend
Unused
:link
A clickable link.
:list
A list of items.
:list-box
Unused
:list-item
An item in a list.
:log
Unused
:main
Unused
:marquee
Unused
:math
Unused
:meter
An element that represents a value within a known range.
:menu
A menu.
:menu-bar
A menubar.
:menu-item
An item in a menu.
:menu-item-checkbox
A check item in a menu.
:menu-item-radio
A radio item in a menu.
:navigation
Unused
:none
An element that is not represented to accessibility technologies.
:note
Unused
:option
Unused
:presentation
An element that is not represented to accessibility technologies.
:progress-bar
An element that displays the progress status for tasks that take a long time.
:radio
A checkable input in a group of radio roles, only one of which can be checked at a time.
:radio-group
Unused
:range
Abstract role.
:region
Unused
:row
A row in a columned list.
:row-group
Unused
:row-header
Unused
:scrollbar
A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.
:search
Unused
:search-box
A type of textbox intended for specifying search criteria.
:section
Abstract role.
:section-head
Abstract role.
:select
Abstract role.
:separator
A divider that separates and distinguishes sections of content or groups of menuitems.
:slider
A user input where the user selects a value from within a given range.
:spin-button
A form of range that expects the user to select from among discrete choices.
:status
Unused
:structure
Abstract role.
:switch
A type of checkbox that represents on/off values, as opposed to checked/unchecked values.
:tab
An item in a list of tab used for switching pages.
:table
Unused
:tab-list
A list of tabs for switching pages.
:tab-panel
A page in a notebook or stack.
:text-box
A type of input that allows free-form text as its value.
:time
Unused
:timer
Unused
:toolbar
Unused
:tooltip
Unused
:tree
Unused
:tree-grid
A treeview-like, columned list.
:tree-item
Unused
:widget
An interactive component of a graphical user interface. This is the role that GTK uses by default for widgets.
:window
An application window.
:toggle-button
A type of push button which stays pressed until depressed by a second activation. Since: 4.10
:application
A toplevel element of a graphical user interface. This is the role that GTK uses by default for windows. Since 4.12
:paragraph
A paragraph of content. Since 4.14
:block-quote
A section of content that is quoted from another source. Since 4.14
:article
A section of a page that consists of a composition that forms an independent part of a document, page, or site. Since 4.14
:comment
A comment contains content expressing reaction to other content. Since 4.14
:terminal
A virtual terminal. Since 4.14
Details:
The accessible role for a gtk:accessible implementation. Abstract roles are only used as part of the ontology. Application developers must not use abstract roles in their code.
See also:
2024-5-25
GEnum gtk:accessible-state
Declaration:
(gobject:define-genum "GtkAccessibleState" gtk:accessible-state
  (:export t
   :type-initializer "gtk_accessible_state_get_type")
   :busy
   :checked
   :disabled
   :expanded
   :hidden
   :invalid
   :pressed
   :selected
   #+gtk-4-12
   :visited)  
Values:
:busy
A "busy" state. This state has boolean values.
:checked
A "checked" state. Indicates the current state of a gtk:check-button widget. Value type: gtk:accessible-tristate enumeration
:disabled
A "disabled" state. Corresponds to the sensitive property on the gtk:widget object. It indicates a UI element that is perceivable, but not editable or operable. Value type: boolean
:expanded
An "expanded" state. Corresponds to the expanded property on the gtk:expander widget. Value type: boolean or undefined
:hidden
A "hidden" state. Corresponds to the visible property on the gtk:widget object. You can use this state explicitly on UI elements that should not be exposed to an assistive technology. See also the :disabled value. Value type: boolean
:invalid
An "invalid" state. Set when a widget is showing an error. Value type: gtk:accessible-invalid-state enumeration
:pressed
A "pressed" state. Indicates the current state of a gtk:toggle-button widget. Value type: gtk:accessible-tristate enumeration
:selected
A "selected" state. Set when a widget is selected. Value type: boolean or undefined
:visited
Indicates that a widget with the :link role has been visited. Value type: boolean. Since 4.12
Details:
The possible accessible states of a gtk:accessible widget.
See also:
2024-4-24
GEnum gtk:accessible-property
Declaration:
(gobject:define-genum "GtkAccessibleProperty" accessible-property
  (:export t
   :type-initializer "gtk_accessible_property_get_type")
  :autocomplete
  :description
  :has-popup
  :key-shortcuts
  :label
  :level
  :modal
  :multi-line
  :multi-selectable
  :orientation
  :placeholder
  :read-only
  :required
  :role-description
  :sort
  :value-max
  :value-min
  :value-now
  :value-text
  :help-text)  
Values:
:auto-complete
Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. Value type: gtk:accessible-autocomplete enumeration
:description
Defines a string value that describes or annotates the current element. Value type: string
:has-popup
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
:key-shortcuts
Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. Value type: string
:label
Defines a string value that labels the current element. Value type: string
:level
Defines the hierarchical level of an element within a structure. Value type: integer
:modal
Indicates whether an element is modal when displayed. Value type: boolean
:multi-line
Indicates whether a text box accepts multiple lines of input or only a single line. Value type: boolean
:multi-selectable
Indicates that the user may select more than one item from the current selectable descendants. Value type: boolean
:orientation
Indicates whether the orientation of the element is horizontal, vertical, or unknown/ambiguous. Value type: gtk:orientation enumeration
:placeholder
Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. Value type: string
:read-only
Indicates that the element is not editable, but is otherwise operable. Value type: boolean
:required
Indicates that user input is required on the element before a form may be submitted. Value type: boolean
:role-description
Defines a human-readable, author-localized description for the role of an element. Value type: string
:sort
Indicates if items in a table or grid are sorted in ascending or descending order. Possible property values are in the gtk:accessible-sort enumeration. Value type: gtk:accessible-sort enumeration
:value-max
Defines the maximum allowed value for a range widget. Value type: double
:value-min
Defines the minimum allowed value for a range widget. Value type: double
:value-now
Defines the current value for a range widget. Value type: double
:value-text
Defines the human readable text alternative of aria-valuenow for a range widget. Value type: string
:help-text
Defines a string value that provides a description of non-standard keyboard interactions of the current element. Value type: string. Since 4.16
Details:
The possible accessible properties of a gtk:accessible widget.
See also:
2024-10-13
GEnum gtk:accessible-relation
Declaration:
(gobject:define-genum "GtkAccessibleRelation" accessible-relation
  (:export t
   :type-initializer "gtk_accessible_relation_get_type")
  :active-descendant
  :col-count
  :col-index
  :col-index-text
  :col-span
  :controls
  :described-by
  :details
  :error-message
  :flow-to
  :labelled-by
  :owns
  :pos-in-set
  :row-count
  :row-index
  :row-index-text
  :row-span
  :set-size)  
Values:
:active-descendant
Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application. Value type: reference
:col-count
Defines the total number of columns in a table, grid, or treegrid. Value type: integer
:col-index
Defines a column index of the element or position with respect to the total number of columns within a table, grid, or treegrid. Value type: integer
:col-index-text
Defines a human readable text alternative of the :col-index value. Value type: string
:col-span
Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer
:controls
Identifies the element (or elements) whose contents or presence are controlled by the current element. Value type: reference
:described-by
Identifies the element (or elements) that describes the object. Value type: reference
:details
Identifies the element (or elements) that provide additional information related to the object. Value type: reference
:error-message
Identifies the element that provides an error message for an object. Value type: reference
:flow-to
Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference
:labelled-by
Identifies the element (or elements) that labels the current element. Value type: reference
:owns
Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between elements where the widget hierarchy cannot be used to represent the relationship. Value type: reference
:pos-in-set
Defines a number or position of the element in the current set of listitems or treeitems. Value type: integer
:row-count
Defines the total number of rows in a table, grid, or treegrid. Value type: integer
:row-index
Defines a row index or position of the element with respect to the total number of rows within a table, grid, or treegrid. Value type: integer
:row-index-text
Defines a human readable text alternative of aria-rowindex. Value type: string
:row-span
Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer
:set-size
Defines the number of items in the current set of listitems or treeitems. Value type: integer
Details:
The possible accessible relations of a gtk:accessible widget. Accessible relations can be references to other widgets, integers or strings.
See also:
2024-4-24
GEnum gtk:accessible-tristate
Declaration:
(gobject:define-genum "GtkAccessibleTristate" accessible-tristate
  (:export t
   :type-initializer "gtk_accessible_tristate_get_type")
  :false
  :true
  :mixed)  
Values:
:false
The state is "false".
:true
The state is "true".
:mixed
The state is "mixed".
Details:
The possible values for the :pressed accessible state. Note that the :false and :true values have the same values as false and true.
See also:
2024-4-24
GEnum gtk:accessible-invalid-state
Declaration:
(gobject:define-genum "GtkAccessibleInvalidState" accessible-invalid-state
  (:export t
   :type-initializer "gtk_accessible_invalid_state_get_type")
  :false
  :true
  :grammar
  :spelling)  
Values:
:false
There are no detected errors in the value.
:true
The value entered by the user has failed validation.
:grammar
A grammatical error was detected.
:spelling
A spelling error was detected.
Details:
The possible values for the :invalid accessible state. Note that the :false and :true values have the same values as false and true.
See also:
2024-4-24
GEnum gtk:accessible-autocomplete
Declaration:
(gobject:define-genum "GtkAccessibleAutocomplete" accessible-autocomplete
  (:export t
   :type-initializer "gtk_accessible_autocomplete_get_type")
  :none
  :inline
  :list
  :both)  
Values:
:none
Automatic suggestions are not displayed.
:inline
When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret.
:list
When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
:both
When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.
Details:
The possible values for the :autocomplete accessible property.
See also:
2024-4-24
GEnum gtk:accessible-sort
Declaration:
(gobject:define-genum "GtkAccessibleSort" accessible-sort
  (:export t
   :type-initializer "gtk_accessible_sort_get_type")
  :none
  :ascending
  :descending
  :other)  
Values:
:none
There is no defined sort applied to the column.
:ascending
Items are sorted in ascending order by this column.
:descending
Items are sorted in descending order by this column.
:other
A sort algorithm other than ascending or descending has been applied.
Details:
The possible values for the :sort accessible property.
See also:
2024-4-24
GEnum gtk:accessible-platform-state
Declaration:
(gobject:define-genum "GtkAccessiblePlatformState" accessible-platform-state
  (:export t
   :type-initializer "gtk_accessible_platform_state_get_type")
  (:focusable 0)
  (:focused 1)
  (:active 2))  
Values:
:focusable
Whether the accessible can be focused.
:focused
Whether the accessible has focus.
:active
Whether the accessible is active.
Details:
The various platform states which can be queried using the gtk:accessible-platform-state function.

Since 4.10
See also:
2024-5-8
Interface gtk:accessible
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
gtk:about-dialog, gtk:accessible-range, gtk:accessible-text, gtk:action-bar, gtk:app-chooser-button, gtk:app-chooser-dialog, gtk:app-chooser-widget, gtk:application-window, gtk:aspect-frame, gtk:assistant, gtk:box, gtk:button, gtk:calendar, gtk:cell-view, gtk:center-box, gtk:check-button, gtk:color-button, gtk:color-chooser-dialog, gtk:color-chooser-widget, gtk:color-dialog-button, gtk:column-view, gtk:combo-box, gtk:combo-box-text, gtk:dialog, gtk:drag-icon, gtk:drawing-area, gtk:drop-down, gtk:editable-label, gtk:emoji-chooser, gtk:entry, gtk:expander, gtk:file-chooser-dialog, gtk:file-chooser-widget, gtk:fixed, gtk:flow-box, gtk:flow-box-child, gtk:font-button, gtk:font-chooser-dialog, gtk:font-chooser-widget, gtk:font-dialog-button, gtk:frame, gtk:gl-area, gtk:graphics-offload, gtk:grid, gtk:grid-view, gtk:header-bar, gtk:icon-view, gtk:image, gtk:info-bar, gtk:inscription, gtk:label, gtk:level-bar, gtk:link-button, gtk:list-base, gtk:list-box, gtk:list-box-row, gtk:lock-button, gtk:media-controls, gtk:menu-button, gtk:message-dialog, gtk:notebook, gtk:overlay, gtk:page-setup-unix-dialog, gtk:paned, gtk:password-entry, gtk:picture, gtk:popover, gtk:popover-menu, gtk:popover-menu-bar, gtk:print-unix-dialog, gtk:progress-bar, gtk:range, gtk:revealer, gtk:scale, gtk:scale-button, gtk:scrollbar, gtk:scrolled-window, gtk:search-bar, gtk:search-entry, gtk:separator, gtk:shortcut-label, gtk:shortcuts-group, gtk:shortcuts-section, gtk:shortcuts-shortcut, gtk:shortcuts-window, gtk:spin-button, gtk:spinner, gtk:stack, gtk:stack-page, gtk:stack-sidebar, gtk:stack-switcher, gtk:statusbar, gtk:switch, gtk:text, gtk:text-view, gtk:toggle-button, gtk:tree-expander, gtk:tree-view, gtk:video, gtk:viewport, gtk:volume-button, gtk:widget, gtk:window, gtk:window-controls, gtk:window-handle
Direct Slots:
accessible-role
The accessible-role property of type gtk:accessible-role (Read / Write)
The accessible role of the given assistive implementation. The accessible role cannot be changed once set.
Slot Access Functions:
Details:
The gtk:accessible interface is an interface for describing UI elements for Assistive Technologies. Every accessible implementation has: The role cannot be changed after instantiating a gtk:accessible implementation.

The attributes are updated every time a state of a UI element changes in a way that should be reflected by assistive technologies. For instance, if a widget visibility changes, the :hidden state will also change to reflect the visible property of the widget.

Every accessible implementation is part of a tree of accessible objects. Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the Gtk.AccessibleInterface.get_accessible_parent, Gtk.AccessibleInterface.get_first_accessible_child and Gtk.AccessibleInterface.get_next_accessible_sibling virtual functions. Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you do not control, it is necessary to ensure the correct shape of the a11y tree by calling the gtk:accessible-accessible-parent function and updating the sibling by the gtk:accessible-update-next-accessible-sibling function.
See also:
2024-5-8
Accessor gtk:accessible-accessible-role (object)
Syntax:
(gtk:accessible-accessible-role object) => role
(setf (gtk:accessible-accessible-role object) role)
Arguments:
object -- a gtk:accessible widget
role -- a value of the gtk:accessible-role enumeration
Details:
Accessor of the accessible-role slot of the gtk:accessible class. Retrieves the gtk:accessible-role value for the given gtk:accessible widget.
See also:
2024-5-8
Function gtk:accessible-property-init-value (property value)
Arguments:
property -- a gtk:accessible-property value
gvalue -- an uninitialized g:value instance
Details:
Initializes gvalue with the appropriate type for property. This function is mostly meant for language bindings, in conjunction with the gtk:accessible-update-property-value function.
See also:
gtk:accessible-property
gtk:accessible-update-property-value
2024-11-5
Function gtk:accessible-relation-init-value (relation value)
Arguments:
relation -- a gtk:accessible-relation value
gvalue -- an uninitialized g:value value
Details:
Initializes value with the appropriate type for relation. This function is mostly meant for language bindings, in conjunction with the gtk:accessible-update-relation-value function.
See also:
gtk:accessible-relation
gtk:accessible-update-relation-value
2024-11-5
Function gtk:accessible-state-init-value (state value)
Arguments:
state -- a gtk:accessible-state value
gvalue -- an uninitialized g:value value
Details:
Initializes gvalue with the appropriate type for state. This function is mostly meant for language bindings, in conjunction with the gtk:accessible-update-state-value function.
See also:
gtk:accessible-state
gtk:accessible-update-state-value
2024-11-5
Function gtk:accessible-accessible-parent (accessible)
Syntax:
(gtk:accessible-accessible-parent accessible) => parent
(setf (gtk:accessible-accessible-parent accessible) parent)
(setf (gtk:accessible-accessible-parent accessible sibling) parent)
Arguments:
accessible -- a gtk:accessible object
parent -- a parent gtk:accessible object
sibling -- a sibling gtk:accessible object
Details:
The gtk:accessible-accessible-parent function retrieves the accessible parent for an accessible object. This function returns nil for top level widgets. The (setf gtk:accessible-accessible-parent) function sets the parent and sibling of an accessible object.

This function is meant to be used by accessible implementations that are not part of the widget hierarchy, but act as a logical bridge between widgets. For instance, if a widget creates an object that holds metadata for each child, and you want that object to implement the gtk:accessible interface, you will use this function to ensure that the parent of each child widget is the metadata object, and the parent of each metadata object is the container widget.

Since 4.10
See also:
2024-11-5
Function gtk:accessible-at-context (accessible)
Arguments:
accessible -- a gtk:accessible object
Returns:
The gtk:at-context object with the accessible implementaton object.
Details:
Retrieves the accessible implementation for the given accessible.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-bounds (accessible)
Syntax:
(gtk:accessible-bounds accessible) => x, y, width, height
Arguments:
accessible -- a gtk:accessible object
Returns:
x -- an integer with the x coordinate of the top left corner of the accessible object
y -- an integer with the y coordinate of the top left corner of the accessible object
width -- an integer with the width of the accessible object
height -- an integer with the height of the accessible object
Details:
Queries the coordinates and dimensions of the accessible object. This functionality can be overridden by gtk:accessible implementations, for example, to get the bounds from an ignored child widget.

If the bounds are not valid, nil is returned.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-first-accessible-child (accessible)
Arguments:
accessible -- a gtk:accessible object
Returns:
The gtk:accessible object with the first accessible child.
Details:
Retrieves the first accessible child of an accessible object.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-next-accessible-sibling (accessible)
Arguments:
accessible -- a gtk:accessible object
Returns:
The gtk:accessible object with the next accessible sibling.
Details:
Retrieves the next accessible sibling of an accessible object.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-platform-state (accessible state)
Arguments:
accessible -- a gtk:accessible object
state -- a gtk:accessible-platform-state value to query
Returns:
The boolean value of state for the accessible object.
Details:
Query a platform state, such as focus. See the gtk:accessible-platform-changed function.

This functionality can be overridden by the gtk:accessible implementations, for example, to get platform state from an ignored child widget, as is the case for gtk:text wrappers.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-reset-property (accessible property)
Arguments:
accessible -- a gtk:accessible object
property -- a gtk:accessible-property value
Details:
Resets the accessible property value to its default value.
See also:
#2024-11-5
Function gtk:accessible-reset-relation (accessible relation)
Arguments:
accessible -- a gtk:accessible widget
relation -- a gtk:accessible-relation value
Details:
Resets the accessible relation value to its default value.
See also:
#2024-11-5
Function gtk:accessible-reset-state (accessible state)
Arguments:
accessible -- a gtk:accessible widget
state -- a gtk:accessible-state value
Details:
Resets the accessible state value to its default value.
See also:
#2024-11-5
Function gtk:accessible-update-next-accessible-sibling (accessible sibling)
Arguments:
accessible -- a gtk:accessible object
sibling -- a gtk:accessible object with the new next accessible sibling to set, the argument can be nil
Details:
Updates the next accessible sibling of accessible. That might be useful when a new child of a custom gtk:accessible object is created, and it needs to be linked to a previous child.

Since 4.10
See also:
#2024-11-5
Function gtk:accessible-update-property (accessible properties values)
Arguments:
accessible -- a gtk:accessible object
properties -- a list of gtk:accessible-property values
values -- a list of g:value instances, one for each property
Details:
Updates a list of accessible properties. See the gtk:accessible-property documentation for the value types of accessible properties.

This function should be called by gtk:widget types whenever an accessible property change must be communicated to assistive technologies.
See also:
#2024-11-5
Function gtk:accessible-update-relation (accessible relations values)
Arguments:
accessible -- a gtk:accessible object
relations -- a list of gtk:accessible-relation values
values -- a list of g:value instances, one for each relation
Details:
Updates a list of accessible relations. See the gtk:accessible-relation documentation for the value types of accessible relations.

This function should be called by gtk:widget types whenever an accessible relation change must be communicated to assistive technologies.
See also:
#2024-11-5
Function gtk:accessible-update-state (accessible states values)
Arguments:
accessible -- a gtk:accessible object
states -- a list of gtk:accessible-state values
values -- a list of g:value instances, one for each state
Details:
Updates a list of accessible states. See the gtk:accessible-state documentation for the value types of accessible states.

This function should be called by gtk:widget types whenever an accessible state change must be communicated to assistive technologies.
See also:
#2024-11-5
Function gtk:accessible-announce (accessible message priority)
Arguments:
accessible -- a gtk:accessible object
message -- a string with the message to announce
priority -- a gtk:accessible-announcement-priority value for the priority of the announcement
Details:
Requests the user’s screen reader to announce the given message. This kind of notification is useful for messages that either have only a visual representation or that are not exposed visually at all, for example, a notification about a successful operation.

Also, by using this API, you can ensure that the message does not interrupts the user’s current screen reader output.

Since 4.14
See also:
#2024-11-5

GtkATContext

Class gtk:at-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accessible
The accessible property of type gtk:accessible (Read / Write / Construct only)
The accessible that created the AT context.
accessible-role
The accessible-role property of type gtk:accessible-role (Read / Write / Construct)
The accessible role used by the AT context. Depending on the given role, different states and properties can be set or retrieved.
Default value: :none
display
The display property of type gdk:display (Read / Write)
The display for the AT context.
Returned by:
Details:
The gtk:at-context class is an abstract class provided by GTK to communicate to platform-specific assistive technologies API. Each platform supported by GTK implements a gtk:at-context subclass, and is responsible for updating the accessible state in response to state changes in the gtk:accessible object.
Signal Details:
The "state-change" signal
lambda (context)    :run-first      
context
The gtk:at-context object.
Emitted when the attributes of the accessible for the gtk:at-context instance change.
See also:
2023-8-31
Accessor gtk:at-context-accessible (object)
Syntax:
(gtk:at-context-accessible object) => accessible
Arguments:
object -- a gtk:at-context object
accessible -- a gtk:accessible object
Details:
Accessor of the accessible slot of the gtk:at-context class. Retrieves the gtk:accessible object using this context.
See also:
2023-8-31
Accessor gtk:at-context-accessible-role (object)
Syntax:
(gtk:at-context-accessible-role object) => role
Arguments:
object -- a gtk:at-context object
role -- a gtk:accessible-role value
Details:
Accessor of the accessible-role slot of the gtk:at-context class. Retrieves the accessible role of the context.
See also:
2023-8-31
Accessor gtk:at-context-display (object)
Syntax:
(gtk:at-context-display object) => display
Arguments:
object -- a gtk:at-context object
display -- a gdk:display object
Details:
Accessor of the display slot of the gtk:at-context class.
See also:
2023-8-31
Function gtk:at-context-create (role accessible display)
Arguments:
role -- a gtk:accessible-role value used by the context
accessible -- a gtk:accessible object using the context
display -- a gdk:display object used by the context
Returns:
The new gtk:at-context object.
Details:
Creates a new gtk:at-context instance for the given accessible role, accessible instance, and display connection. The gtk:at-context implementation being instantiated will depend on the platform.
See also:
2023-8-31

Input Methods

GtkIMContext

Class gtk:im-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
input-hints
The input-hints property of type gtk:input-hints (Read / Write)
Hints for the text field behaviour.
input-purpose
The input-purpose property of type gtk:input-purpose (Read / Write)
Purpose of the text field.
Default value: :free-from
Slot Access Functions:
Details:
The gtk:im-context class defines the interface for GTK input methods. An input method is used by GTK text input widgets like the gtk:entry widget to map from key events to Unicode character strings.

An input method may consume multiple key events in sequence before finally outputting the composed result. This is called preediting, and an input method may provide feedback about this process by displaying the intermediate composition states as preedit text. To do so, the gtk:im-context object will emit the "preedit-start", "preedit-changed" and "preedit-end" signals.

For instance, the built-in GTK gtk:im-context-simple input method implements the input of arbitrary Unicode code points by holding down the Control and Shift keys and then typing u followed by the hexadecimal digits of the code point. When releasing the Control and Shift keys, preediting ends and the character is inserted as text. For example,
Ctrl+Shift+u 2 0 A C  
results in the € sign.

Additional input methods can be made available for use by GTK widgets as loadable modules. An input method module is a small shared library which provides a GIOExtension for the extension point named gtk-im-module.

To connect a widget to the users preferred input method, you should use the gtk:im-multicontext class.
Signal Details:
The "commit" signal
lambda (context str)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
str
The string with the completed character(s) entered by the user.
The signal is emitted when a complete input sequence has been entered by the user. This can be a single character immediately after a key press or the final result of preediting.
The "delete-surrounding" signal
lambda (context offset n-chars)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
offset
The integer with the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor.
n-chars
The integer with the number of characters to be deleted.
Returns
True if the signal was handled.
The signal is emitted when the input method needs to delete all or part of the context surrounding the cursor.
The "preedit-changed" signal
lambda (context)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
The signal is emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case the gtk:im-context-preedit-string function returns the empty string.
The "preedit-end" signal
lambda (context)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
The signal is emitted when a preediting sequence has been completed or canceled.
The "preedit-start" signal
lambda (context)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
The signal is emitted when a new preediting sequence starts.
The "retrieve-surrounding" signal
lambda (context)    :run-last      
context
The gtk:im-context object on which the signal is emitted.
Returns
True if the signal was handled.
The signal is emitted when the input method requires the context surrounding the cursor. The callback should set the input method surrounding context by calling the gtk:im-context-surrounding function.
See also:
2023-8-29
Accessor gtk:im-context-input-hints (object)
Syntax:
(gtk:im-context-input-hints object) => hints
(setf (gtk:im-context-input-hints object) hints)
Arguments:
object -- a gtk:im-context object
hints -- a value of the gtk:input-hints enumeration
Details:
Accessor of the input-hints slot of the gtk:im-context class. Hints for the text field behaviour.
See also:
2023-8-29
Accessor gtk:im-context-input-purpose (object)
Syntax:
(gtk:im-context-input-purpose object) => purpose
(setf (gtk:im-context-input-purpose object) purpose)
Arguments:
object -- a gtk:im-context object
purpose -- a value of the gtk:input-purpose enumeration
Details:
Accessor of the input-purpose slot of the gtk:im-context class. Purpose of the text field.
See also:
2023-8-29
Function gtk:im-context-filter-keypress (context event)
Arguments:
context -- a gtk:im-context object
event -- a gdk:event instance with the key event
Returns:
True if the input method handled the key event.
Details:
Allow an input method to internally handle key press and release events. If this function returns true, then no further processing should be done for this key event.
See also:
#2023-10-21

GtkIMContextSimple

Class gtk:im-context-simple
Superclasses:
gtk:im-context, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:im-context-simple class is a simple input method context supporting table-based input methods.

Compose sequences
The gtk:im-context-simple class reads compose sequences from the first of the following files that is found: ~/.config/gtk-4.0/Compose, ~/.XCompose, /usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial Compose file). A subset of the file syntax described in the Compose(5) manual page is supported. Additionally, include "L" loads GTK’s built-in table of compose sequences rather than the locale-specific one from X11.

If none of these files is found, the gtk:im-context-simple class uses a built-in table of compose sequences that is derived from the X11 Compose files.

Note that compose sequences typically start with the Compose_key, which is often not available as a dedicated key on keyboards. Keyboard layouts may map this keysym to other keys, such as the right Control key.

Unicode characters
The gtk:im-context-simple class also supports numeric entry of Unicode characters by typing the Ctrl-Shift-u key, followed by a hexadecimal Unicode codepoint. For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, that is the ģ character.

Dead keys
The gtk:im-context-simple class supports dead keys. For example, typing
dead_acute a  
yields U+00E! LATIN SMALL LETTER_A WITH ACUTE, that is the á character. Note that this depends on the keyboard layout including dead keys.
See also:
2023-8-29
Function gtk:im-context-simple-new ()
Returns:
The new gtk:im-context-simple object.
Details:
Creates a new simple input method.
See also:
2023-8-29

GtkIMMulticontext

Class gtk:im-multicontext
Superclasses:
gtk:im-context, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:im-multicontext class is an input method context supporting multiple, switchable input methods. Text widgets such as gtk:text or gtk:text-view widgets use a gtk:im-multicontext object to implement their im-module property for switching between different input methods.
See also:
2023-8-29
Function gtk:im-multicontext-new ()
Returns:
The new gtk:im-multicontext object.
Details:
Creates a new input method context supporting multiple, switchable input methods.
See also:
2023-8-29

Recently Used Documents

GtkRecentInfo

GBoxed gtk:recent-info
Declaration:
(glib:define-gboxed-opaque gtk:recent-info "GtkRecentInfo"
  :type-initializer "gtk_recent_info_get_type"
  :alloc (error "GtkRecentInfo cannot be created from the Lisp side."))  
Details:
The gtk:recent-info structure constains all the meta-data associated with an entry in the recently used files list. The gtk:recent-info structure is an opaque data structure whose members can only be accessed using the provided API.
See also:
2025-1-11
Function gtk:recent-info-uri (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string with the URI of the resource.
Details:
Gets the URI of the resource.
See also:
2025-1-11
Function gtk:recent-info-display-name (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string with the display name of the resource.
Details:
Gets the name of the resource. If none has been defined, the basename of the resource is obtained.
See also:
2025-1-11
Function gtk:recent-info-description (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string with the description of the resource.
Details:
Gets the (short) description of the resource.
See also:
2025-1-11
Function gtk:recent-info-mime-type (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string with the MIME type of the resource.
Details:
Gets the MIME type of the resource.
See also:
2025-1-11
Function gtk:recent-info-added (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The long integer with the number of seconds elapsed from system's Epoch when the resource was added to the list, or -1 on failure.
Details:
Gets the timestamp, seconds from system's Epoch, when the resource was added to the recently used resources list.
See also:
2025-2-24
Function gtk:recent-info-modified (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The long integer with the number of seconds elapsed from system's Epoch when the resource was last modified, or -1 on failure.
Details:
Gets the timestamp, seconds from system's Epoch, when the resource was last modified.
See also:
2025-2-24
Function gtk:recent-info-visited (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The long integer with the number of seconds elapsed from system's Epoch when the resource was last visited, or -1 on failure.
Details:
Gets the timestamp, seconds from system's Epoch, when the resource was last visited.
See also:
2025-2-24
Function gtk:recent-info-private-hint (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
True if the private flag was found, false otherwise.
Details:
Gets the value of the "private" flag. Resources in the recently used list that have this flag set to true should only be displayed by the applications that have registered them.
See also:
2025-1-11
Function gtk:recent-info-application-info (info name)
Arguments:
info -- a gtk:recent-info instance
name -- a string for the name of the application that has registered this item
Returns:
exec -- a string containing the command line
count -- an integer with the number of times this item was registered
time -- a long integer with the timestamp this item was last registered for this application
Details:
Gets the data regarding the application that has registered the resource pointed by info. If the command line contains any escape characters defined inside the storage specification, they will be expanded.
See also:
2025-2-24
Function gtk:recent-info-applications (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The list of strings with the applications.
Details:
Retrieves the list of applications that have registered this resource.
See also:
2025-1-11
Function gtk:recent-info-last-application (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string with an application name.
Details:
Gets the name of the last application that have registered the recently used resource represented by info.
See also:
2025-1-11
Function gtk:recent-info-has-application (info name)
Arguments:
info -- a gtk:recent-info instance
name -- a string containing an application name
Returns:
True if an application with name name was found, false otherwise.
Details:
Checks whether an application registered this resource using name.
See also:
2025-2-24
Function gtk:recent-info-create-app-info (info name)
Arguments:
info -- a gtk:recent-info instance
name -- a string for the name of the application that should be mapped to a g:app-info object, if nil is used then the default application for the MIME type is used
Returns:
The newly created g:app-info object, or nil.
Details:
Creates a g:app-info object for the specified gtk:recent-info instance.
See also:
#2025-1-11
Function gtk:recent-info-groups (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The list of strings with the groups.
Details:
Returns all groups registered for the recently used item info.
See also:
#2025-2-24
Function gtk:recent-info-has-group (info group)
Arguments:
info -- a gtk:recent-info instance
group -- a string with the name of a group
Returns:
True if the group was found.
Details:
Checks whether group appears inside the groups registered for the recently used item info.
See also:
#2025-2-24
Function gtk:recent-info-gicon (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The g:icon icon containing the icon, or nil.
Details:
Retrieves the icon associated to the resource MIME type.
See also:
#2025-1-11
Function gtk:recent-info-short-name (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The string in UTF-8 encoding.
Details:
Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers to "file:///foo/bar.txt" will yield "bar.txt".
See also:
#2025-1-11
Function gtk:recent-info-uri-display (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The UTF-8 string containing the URI of the resource or nil.
Details:
Gets a displayable version of the URI of the resource. If the resource is local, it returns a local path. If the resource is not local, it returns the UTF-8 encoded content of the function gtk:recent-info-uri.
See also:
#2025-2-24
Function gtk:recent-info-age (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
The positive integer containing the number of days elapsed since the time this resource was last modified.
Details:
Gets the number of days elapsed since the last update of the resource pointed by info.
See also:
#2025-1-11
Function gtk:recent-info-is-local (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
True if the resource is local.
Details:
Checks whether the resource is local or not by looking at the scheme of its URI.
See also:
#2025-1-11
Function gtk:recent-info-exists (info)
Arguments:
info -- a gtk:recent-info instance
Returns:
True if the resource exists.
Details:
Checks whether the resource pointed by info still exists. At the moment this check is done only on resources pointing to local files.
See also:
#2025-2-24
Function gtk:recent-info-match (info1 info2)
Arguments:
info1 -- a gtk:recent-info
info2 -- a gtk:recent-info
Returns:
True if both gtk:recent-info instances point to the same resource, false otherwise.
Details:
Checks whether two gtk:recent-info instances point to the same resource.
See also:
#2025-1-11

GtkRecentManager

Class gtk:recent-manager
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
filename
The filename property of type :string (Read / Write / Construct)
The full path to the file to be used to store and read the recently used resources list.
Default value: nil
size
The size property of type :int (Read)
The size of the recently used resources list.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:recent-manager object provides a facility for adding, removing and looking up recently used files. Each recently used file is identified by its URI, and has meta-data associated to it, like the names and command lines of the applications that have registered it, the number of time each application has registered the same file, the MIME type of the file and whether the file should be displayed only by the applications that have registered it. The recently used files list is per user.

The gtk:recent-manager object acts like a database of all the recently used files. You can create new gtk:recent-manager objects, but it is more efficient to use the default manager created by GTK. Adding a new recently used file is as simple as:
(let ((uri "file:///home/ ... uri to add ...")
      (manager (gtk:recent-manager-default)))
  (gtk:recent-manager-add-item manager uri)
  ... )  
The gtk:recent-manager will try to gather all the needed information from the file itself through GIO. Looking up the meta-data associated with a recently used file given its URI requires calling the gtk:recent-manager-lookup-item function:
(let* ((uri "file:///home/ ... uri to look up ...")
       (manager (gtk:recent-manager-default))
       (info (gtk:recent-manager-lookup-item manager uri)))
    (when info
      ;; Use the object
      ... ))  
In order to retrieve the list of recently used files, you can use the gtk:recent-manager-items function, which returns a list of gtk:recent-info instances.

Note that the maximum age of the recently used files list is controllable through the gtk-recent-files-max-age setting of the gtk:settings object.
Signal Details:
The "changed" signal
lambda (manager)    :run-first      
manager
The gtk:recent-manager object which received the signal.
Emitted when the current recently used resources manager changes its contents, either by calling the gtk:recent-manager-add-item function or by another application.
2025-3-24
Accessor gtk:recent-manager-filename (object)
Syntax:
(gtk:recent-manager-filename object) => filename
(setf (gtk:recent-manager-filename object) filename)
Arguments:
object -- a gtk:recent-manager object
filename -- a string with the full path to the file
Details:
Accessor of the filename slot of the gtk:recent-manager class. The full path to the file to be used to store and read the recently used resources list.
See also:
2025-1-6
Accessor gtk:recent-manager-size (object)
Syntax:
(gtk:recent-manager-size object) => size
(setf (gtk:recent-manager-size object) size)
Arguments:
object -- a gtk:recent-manager object
size -- an integer with the size of the resources list
Details:
Accessor of the size slot of the gtk:recent-manager class. The size of the recently used resources list.
See also:
2025-1-6
Function gtk:recent-manager-new ()
Returns:
The newly created gtk:recent-manager object.
Details:
Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A gtk:recent-manager object monitors the recently used resources list, and emits the "changed" signal each time something inside the list changes.

The gtk:recent-manager object is expensive. Be sure to create it only when needed. You should use the gtk:recent-manager-default function instead.
See also:
2025-1-6
Function gtk:recent-manager-default ()
Returns:
The unique gtk:recent-manager object.
Details:
Gets a unique instance of the default recent manager.
See also:
2024-1-6
Function gtk:recent-manager-add-item (manager uri)
Arguments:
manager -- a gtk:recent-manager object
uri -- a string for a valid URI
Returns:
True if the new item was successfully added to the recently used resources list.
Details:
Adds a new resource, pointed by uri, into the recently used resources list. This function automatically retrieves some of the needed metadata and setting other metadata to common default values.
See also:
2025-1-6
Function gtk:recent-manager-remove-item (manager uri)
Arguments:
manager -- a gtk:recent-manager object
uri -- a string for the URI of the item you wish to remove
Returns:
True if the item pointed by uri has been successfully removed by the recently used resources list, and false otherwise.
Details:
Removes a resource pointed by uri from the recently used resources list handled by a recent manager.
See also:
2025-2-24
Function gtk:recent-manager-lookup-item (manager uri)
Arguments:
manager -- a gtk:recent-manager object
uri -- a string for the URI
Returns:
The gtk:recent-info instance containing information about the resource pointed by uri, or nil if the URI was not registered in the recently used resources list.
Details:
Searches for a URI inside the recently used resources list, and returns a structure containing informations about the resource like its MIME type, or its display name.
See also:
2025-1-6
Function gtk:recent-manager-has-item (manager uri)
Arguments:
manager -- a gtk:recent-manager object
uri -- a string for the URI
Returns:
True if the resource was found, false otherwise.
Details:
Checks whether there is a recently used resource registered with uri inside the recent manager.
See also:
2025-1-6
Function gtk:recent-manager-move-item (manager uri newuri)
Arguments:
manager -- a gtk:recent-manager object
uri -- a string for the URI of a recently used resource
newuri -- a string for the new URI of the recently used resource, or nil to remove the item pointed by uri in the list
Returns:
True on success.
Details:
Changes the location of a recently used resource from uri to newuri. Please note that this function will not affect the resource pointed by the URIs, but only the URI used in the recently used resources list.
See also:
2025-2-24
Function gtk:recent-manager-items (manager)
Arguments:
manager -- a gtk:recent-manager object
Returns:
The list of newly allocated gtk:recent-info instances.
Details:
Gets the list of recently used resources.
See also:
2025-1-6
Function gtk:recent-manager-purge-items (manager)
Arguments:
manager -- a gtk:recent-manager object
Returns:
The integer with the number of items that have been removed from the recently used resources list.
Details:
Purges every item from the recently used resources list.
See also:
#2025-1-6

Gestures and event handling

GtkEventController

GEnum gtk:propagation-phase
Declaration:
(gobject:define-genum "GtkPropagationPhase" propagation-phase
  (:export t
   :type-initializer "gtk_propagation_phase_get_type")
  (:none 0)
  (:capture 1)
  (:bubble 2)
  (:target 3))  
Values:
:none
Events are not delivered.
:capture
Events are delivered in the capture phase. The capture phase happens before the bubble phase, runs from the toplevel down to the event widget. This option should only be used on containers that might possibly handle events before their children do.
:bubble
Events are delivered in the bubble phase. The bubble phase happens after the capture phase, and before the default handlers are run. This phase runs from the event widget, up to the toplevel.
:target
Events are delivered in the default widget event handlers, note that widget implementations must chain up on button, motion, touch and grab broken handlers for controllers in this phase to be run.
Details:
Describes the stage at which events are fed into a gtk:event-controller object.
See also:
2024-7-26
GEnum gtk:propagation-limit
Declaration:
(gobject:define-genum "GtkPropagationLimit" propagation-limit
  (:export t
   :type-initializer "gtk_propagation_limit_get_type")
  (:none 0)
  (:same-native 1))  
Values:
:none
Events are handled regardless of what their target is.
:same-native
Events are only handled if their target is in the same gtk:native widget as the event controllers widget. Note that some event types have two targets (origin and destination).
Details:
Describes limits of a gtk:event-controller object for handling events targeting other widgets.
See also:
2024-7-26
Class gtk:event-controller
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
name
The name property of type :string (Read / Write)
The name for this controller, typically used for debugging purposes.
Default value: nil
propagation-limit
The propagation-limit property of type gtk:propagation-limit (Read / Write)
The limit for which events the controller will handle.
Default value: :same-native
propagation-phase
The propagation-phase property of type gtk:propagation-phase (Read / Write)
The propagation phase at which this controller will handle events.
Default value: :bubble
widget
The widget property of type gtk:widget (Read)
The widget receiving the gdk:event instances that the controller will handle.
Slot Access Functions:
Details:
The gtk:event-controller class is the base class for event controllers. These are ancillary objects associated to widgets, which react to gdk:event instances, and possibly trigger actions as a consequence.

Event controllers are added to a widget with the gtk:widget-add-controller function. It is rarely necessary to explicitly remove a controller with the gtk:widget-remove-controller function.

See the GTK documentation on input handling for an overview of the basic concepts, such as the capture and bubble phases of even propagation.
See also:
2024-7-26
Accessor gtk:event-controller-name (object)
Syntax:
(gtk:event-controller-name object) => name
(setf (gtk:event-controller-name object) name)
Arguments:
object -- a gtk:event-controller object
name -- a string with the name for the controller
Details:
Accessor of the name slot of the gtk:event-controller class. The gtk:event-controller-name function gets the name of the event controller. The (setf gtk:event-controller-name) function sets a name. The name can be used for debugging purposes.
See also:
2024-7-26
Accessor gtk:event-controller-propagation-limit (object)
Syntax:
(gtk:event-controller-propagation-limit object) => limit
(setf (gtk:event-controller-propagation-limit object) limit)
Arguments:
object -- a gtk:event-controller object
limit -- a value of the gtk:propagation-limit enumeration
Details:
Accessor of the propagation-limit slot of the gtk:event-controller class. The gtk:event-controller-propagation-limit function gets the propagation limit of the event controller. The (setf gtk:event-controller-propagation-limit) function sets the event propagation limit.

If the limit is set to :same-native, the controller will not handle events that are targeted at widgets on a different surface, such as popovers.
See also:
2024-7-26
Accessor gtk:event-controller-propagation-phase (object)
Syntax:
(gtk:event-controller-propagation-phase object) => phase
(setf (gtk:event-controller-propagation-phase object) phase)
Arguments:
object -- a gtk:event-controller object
phase -- a value of the gtk:propagation-phase enumeration
Details:
Accessor of the propagation-phase slot of the gtk:event-controller class. The gtk:event-controller-propagation-phase function gets the propagation phase at which controller handles events. The (setf gtk:event-controller-propagation-phase) function sets the propagation phase.

If phase is :none, no automatic event handling will be performed, but other additional gesture maintenance will.
See also:
2024-7-26
Accessor gtk:event-controller-widget (object)
Syntax:
(gtk:event-controller-widget object) => widget
Arguments:
object -- a gtk:event-controller object
widget -- a gtk:widget object
Details:
Accessor of the widget slot of the gtk:event-controller class. The gtk:event-controller-widget function returns the widget the event controller relates to.
See also:
2024-7-26
Function gtk:event-controller-reset (controller)
Arguments:
controller -- a gtk:event-controller object
Details:
Resets the controller to a clean state.
See also:
2024-7-26
Function gtk:event-controller-current-event (controller)
Arguments:
controller -- a gtk:event-controller object
Returns:
The gdk:event instance that is currently handled by controller, or nil.
Details:
Returns the event that is currently being handled by the controller, and nil at other times.
See also:
2024-7-26
Function gtk:event-controller-current-event-device (controller)
Arguments:
controller -- a gtk:event-controller object
Returns:
The gdk:device object that is currently handled by controller.
Details:
Returns the device of the event that is currently being handled by the controller, and nil otherwise.
See also:
2024-7-26
Function gtk:event-controller-current-event-state (controller)
Arguments:
controller -- a gtk:event-controller object
Returns:
The gdk:modifier-type state that is currently handled by controller.
Details:
Returns the modifier state of the event that is currently being handled by the controller.
See also:
2024-7-26
Function gtk:event-controller-current-event-time (controller)
Arguments:
controller -- a gtk:event-controller object
Returns:
The unsigned integer with the timestamp of the event that is currently handled by controller.
Details:
Returns the timestamp of the event that is currently being handled by the controller, and 0 otherwise.
See also:
2024-7-26

GtkEventControllerKey

Class gtk:event-controller-key
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:event-controller-key object is an event controller meant for situations where you need access to key events.
Signal Details:
The "im-update" signal
lambda (controller)    :run-last      
controller
The gtk:event-controller-key object which received the signal.
The signal is emitted whenever the input method context filters away a keypress and prevents the controller receiving it. See the gtk:event-controller-key-im-context and gtk:im-context-filter-keypress functions.
The "key-pressed" signal
lambda (controller keyval keycode state)    :run-last      
controller
The gtk:event-controller-key object which received the signal.
keyval
The unsigned integer with the pressed key.
keycode
The unsigned integer with the raw code of the pressed key.
state
The gdk:modifier-type bitmask representing the state of modifier keys and pointer buttons.
Returns
True if the key press was handled, false otherwise.
The signal is emitted whenever a key is pressed.
The "key-released" signal
lambda (controller keyval keycode state)    :run-last      
controller
The gtk:event-controller-key object which received the signal.
keyval
The unsigned integer with the released key.
keycode
The unsigned integer with the raw code of the released key.
state
The gdk:modifier-type bitmask representing the state of modifier keys and pointer buttons.
The signal is emitted whenever a key is released.
The "modifiers" signal
lambda (controller state)    :run-last      
controller
The gtk:event-controller-key object on which received the signal.
state
The gdk:modifier-type bitmask, representing the state of modifier keys and pointer buttons.
Returns
The boolean whether to ignore modifiers.
This signal is emitted whenever the state of modifier keys and pointer buttons change.
See also:
2024-7-26
Function gtk:event-controller-key-new ()
Returns:
The new gtk:event-controller-key object.
Details:
Creates a new event controller that will handle key events.
See also:
2024-7-26
Function gtk:event-controller-key-im-context (controller)
Syntax:
(gtk:event-controller-key-im-context controller) => context
(setf (gtk:event-controller-key-im-context controller) context)
Arguments:
controller -- a gtk:event-controller-key object
context -- a gtk:im-context object
Details:
The gtk:event-controller-key-im-context function gets the input method context of the key controller. The (setf gtk:event-controller-key-im-context) function sets the input method context.
See also:
2024-7-26
Function gtk:event-controller-key-forward (controller widget)
Arguments:
controller -- a gtk:event-controller-key object
widget -- a gtk:widget object
Returns:
The boolean whether the widget handled the event
Details:
Forwards the current event of this controller to a widget. This function can only be used in handlers for the "key-pressed", "key-released" or "modifiers" signals.
See also:
#2024-7-26
Function gtk:event-controller-key-group (controller)
Arguments:
controller -- a gtk:event-controller-key object
Returns:
The unsigned integer with the key group.
Details:
Gets the key group of the current event of the controller.
See also:
2024-7-26

GtkEventControllerFocus

Class gtk:event-controller-focus
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
contains-focus
The contains-focus property of type :boolean (Read)
True if focus is contained in the controllers widget. See the is-focus property for whether the focus is in the widget itself or inside a descendent. When handling focus events, this property is updated before the "enter" or "leave" signals are emitted.
Default value: false
is-focus
The is-focus property of type :boolean (Read)
True if focus is contained in the controllers widget, as opposed to in a descendent widget. When handling focus events, this property is updated before the "enter" or "leave" signals are emitted.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:event-controller-focus class is an event controller to keep track of keyboard focus.

The event controller offers the "enter" and "leave" signals, as well as the is-focus and contains-focus properties which are updated to reflect focus changes inside the widget hierarchy that is rooted at the controllers widget.
Signal Details:
The "enter" signal
lambda (controller)    :run-last      
controller
The gtk:event-controller-focus object which received the signal.
The signal is emitted whenever the focus enters into the widget or one of its descendents. Note that this means you may not get an "enter" signal even though the widget becomes the focus location, in certain cases, such as when the focus moves from a descendent of the widget to the widget itself. If you are interested in these cases, you can monitor the is-focus property for changes.
The "leave" signal
lambda (controller)    :run-last      
controller
The gtk:event-controller-focus object which received the signal.
The signal is emitted whenever the focus leaves the widget hierarchy that is rooted at the widget that the controller is attached to. Note that this means you may not get a "leave" signal even though the focus moves away from the widget, in certain cases, such as when the focus moves from the widget to a descendent. If you are interested in these cases, you can monitor the is-focus property for changes.
See also:
2024-7-26
Accessor gtk:event-controller-focus-contains-focus (object)
Syntax:
(gtk:event-controller-focus-contains-focus object) => contains
Arguments:
object -- a gtk:event-controller-focus object
contains -- a boolean whether focus is within object
Details:
Accessor of the contains-focus slot of the gtk:event-controller-focus class. The gtk:event-controller-focus-contains-focus function returns true if focus is within the controllers widget or one of its children.
See also:
2024-7-26
Accessor gtk:event-controller-focus-is-focus (object)
Syntax:
(gtk:event-controller-focus-is-focus object) => is-focus
Arguments:
object -- a gtk:event-controller-focus object
is-focus -- a boolean whether focus is within the controllers widget, but not one of its children
Details:
Accessor of the is-focus slot of the gtk:event-controller-focus class. The gtk:event-controller-focus-is-focus function returns true if focus is within the controllers widget, but not one of its children.
See also:
2024-7-26
Function gtk:event-controller-focus-new ()
Returns:
Details:
Creates a new event controller that will handle focus events.
See also:
2024-7-26

GtkEventControllerLegacy

Class gtk:event-controller-legacy
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:event-controller-legacy object is an event controller that gives you direct access to the event stream. It should only be used as a last resort if none of the other event controllers or gestures do the job.
Signal Details:
The "event" signal
lambda (controller event)    :run-last      
controller
The gtk:event-controller-legacy object which received the signal.
event
The gdk:event instance which triggered the signal.
Returns
True to stop other handlers from being invoked for the event and the emission of this signal. False to propagate the event further.
The signal is emitted for each GDK event delivered to controller.
See also:
2024-7-26
Function gtk:event-controller-legacy-new ()
Returns:
The newly created gtk:event-controller-legacy object.
Details:
Creates a new legacy event controller.
See also:
2024-7-26

GtkEventControllerScroll

GFlags gtk:event-controller-scroll-flags
Declaration:
(gobject:define-gflags "GtkEventControllerScrollFlags" event-controller-scroll-flags
  (:export t
   :type-initializer "gtk_event_controller_scroll_flags_get_type")
  (:none 0)
  (:vertical 1)
  (:horizontal 2)
  (:discrete 4)
  (:kinetic 8)
  (:both-axes 3))  
Values:
:none
Do not emit scroll.
:vertical
Emit scroll with vertical deltas.
:horizontal
Emit scroll with horizontal deltas.
:discrete
Only emit deltas that are multiples of 1.
:kinetic
Emit the "decelerate" signal after continuous scroll finishes.
:both-axes
Emit scroll on both axes.
Details:
Describes the behavior of a gtk:event-controller-scroll object.
See also:
2024-7-26
Class gtk:event-controller-scroll
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
flags
The flags property of type gtk:event-controller-scroll-flags (Read / Write)
The flags affecting event controller behavior.
Returned by:
Slot Access Functions:
Details:
The gtk:event-controller-scroll object is an event controller is an event controller that handles scroll events. It is capable of handling both discrete and continuous scroll events, abstracting them both with the "scroll" signal. Deltas in the discrete case are multiples of 1. In the case of continuous scroll events, the gtk:event-controller-scroll object encloses all "scroll" events between two "scroll-begin" and "scroll-end" signals.

The behavior of the event controller can be modified by the flags given at creation time, or modified at a later point through the gtk:event-controller-scroll-flags function, for example, because the scrolling conditions of the widget changed.

The controller can be set up to emit motion for either/both vertical and horizontal scroll events through :vertical, :horizontal and :both-axes. If any axis is disabled, the respective "scroll" delta will be 0. Vertical scroll events will be translated to horizontal motion for the devices incapable of horizontal scrolling.

The event controller can also be forced to emit discrete events on all devices through the :discrete flag. This can be used to implement discrete actions triggered through scroll events, for example, switching across combobox options.

The :kinetic flag toggles the emission of the "decelerate" signal, emitted at the end of scrolling with two X/Y velocity arguments that are consistent with the motion that was received.
Signal Details:
The "decelerate" signal
lambda (controller xvel yvel)    :run-first      
controller
The gtk:event-controller-scroll object which received the signal.
xvel
The double float with the x velocity
yvel
The double float with the y velocity
Emitted after scroll is finished if the :kinetic flag is set. The xvel and yvel parameters express the initial velocity that was imprinted by the scroll events. The parameters are expressed in pixels/ms.
The "scroll" signal
lambda (controller dx dy)    :run-first      
controller
The gtk:event-controller-scroll object which received the signal.
dx
The double float with the x delta
dy
The double float with the y delta
Signals that the widget should scroll by the amount specified by the dx and dy parameters.
The "scroll-begin" signal
lambda (controller)    :run-first      
controller
The gtk:event-controller-scroll object which received the signal.
Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it.
The "scroll-end" signal
lambda (controller)    :run-first      
controller
The gtk:event-controller-scroll object which received the signal.
Signals that a new scrolling operation has finished. It will only be emitted on devices capable of it.
See also:
2024-7-26
Accessor gtk:event-controller-scroll-flags (object)
Syntax:
(gtk:event-controller-scroll-flags object) => flags
(setf (gtk:event-controller-scroll-flags object) flags)
Arguments:
Details:
Accessor of the flags slot of the gtk:event-controller-scroll class. The gtk:event-controller-scroll-flags function gets the flags conditioning the scroll controller behavior. The (setf gtk:event-controller-scroll-flags) function sets the flags.
See also:
2024-7-26
Function gtk:event-controller-scroll-new (flags)
Arguments:
flags -- a gtk:event-controller-scroll-flags value affecting the controller behaviour
Returns:
Details:
Creates a new event controller that will handle scroll events.
See also:
2024-7-26
Function gtk:event-controller-scroll-unit (scroll)
Arguments:
scroll -- a gtk:event-controller-scroll object
Returns:
The gdk:scroll-unit value with the scroll unit.
Details:
Gets the scroll unit of the last "scroll" signal received. Always returns :wheel if the :discrete flag is set.

Since 4.8
See also:
2024-7-26

GtkEventControllerMotion

Class gtk:event-controller-motion
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
contains-pointer
The contains-pointer property of type :boolean (Read)
True if the pointer is in the controllers widget or a descendant. When handling crossing events, this property is updated before the "enter" signal but after the "leave" signal is emitted.
Default value: false
is-pointer
The is-pointer property of type :boolean (Read)
True if the pointer is contained in the controllers widget, as opposed to in a descendent widget. When handling crossing events, this property is updated before the "enter" signal, but after the "leave" signal is emitted.
Default value: false
Returned by:
Details:
The gtk:event-controller-motion object is an event controller tracking the pointer position. The event controller offers "enter" and "leave" signals, as well as is-pointer and contains-pointer properties which are updated to reflect changes in the pointer position as it moves over the widget.
Signal Details:
The "enter" signal
lambda (controller x y)    :run-first      
controller
The gtk:event-controller-motion object which received the signal.
x
The double float with the x coordinate.
y
The double float with the y coordinate.
Signals that the pointer has entered the widget.
The "leave" signal
lambda (controller)    :run-first      
controller
The gtk:event-controller-motion object which received the signal.
Signals that the pointer has left the widget.
The "motion" signal
lambda (controller x y)    :run-first      
controller
The gtk:event-controller-motion object which received the signal.
x
The double float with the x coordinate.
y
The double float with the y coordinate.
Emitted when the pointer moves inside the widget.
See also:
2024-7-26
Accessor gtk:event-controller-motion-contains-pointer (object)
Syntax:
(gtk:event-controller-motion-contains-pointer object) => contains
Arguments:
object -- a gtk:event-controller-motion object
contains -- a boolean whether the pointer is within object
Details:
Accessor of the contains-pointer slot of the gtk:event-controller-motion class. The gtk:event-controller-motion-contains-pointer function returns true if the pointer is within the controllers widget or one of its children.
See also:
2024-7-26
Accessor gtk:event-controller-motion-is-pointer (object)
Syntax:
(gtk:event-controller-motion-is-pointer object) => is-pointer
Arguments:
object -- a gtk:event-controller-motion object
is-pointer -- a boolean whether the pointer is within object
Details:
Accessor of the is-pointer slot of the gtk:event-controller-motion class. The gtk:event-controller-motion-is-pointer function returns true if the pointer is within the controllers widget but not one of its children.
See also:
2024-7-26
Function gtk:event-controller-motion-new ()
Returns:
Details:
Creates a new event controller that will handle motion events.
See also:
2024-7-26

GtkGesture

GEnum gtk:event-sequence-state
Declaration:
(gobject:define-genum "GtkEventSequenceState" event-sequence-state
  (:export t
   :type-initializer "gtk_event_sequence_state_get_type")
  (:none 0)
  (:claimed 1)
  (:denied 2))  
Values:
:none
The sequence is handled, but not grabbed.
:claimed
The sequence is handled and grabbed.
:denied
The sequence is denied.
Details:
Describes the state of a gdk:event-sequence instance in a gtk:gesture object.
See also:
2024-7-27
Class gtk:gesture
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
n-points
The n-points property of type :int (Read / Write / Construct only)
The number of touch points that trigger recognition on this gesture.
Allowed values: >= 1
Default value: 1
Slot Access Functions:
Details:
The gtk:gesture object is the base object for gesture recognition. Although this object is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and pointer-based gestures.

The number of touches that a gtk:gesture object need to be recognized is controlled by the n-points property, if a gesture is keeping track of less or more than that number of sequences, it will not check whether the gesture is recognized.

As soon as the gesture has the expected number of touches, it will check regularly if it is recognized, the criteria to consider a gesture as "recognized" is left to gtk:gesture subclasses.

A recognized gesture will then emit the following signals:
  • The "begin" signal when the gesture is recognized.
  • A number of "update" signals, whenever an input event is processed.
  • The "end" signal when the gesture is no longer recognized.
Event propagation
In order to receive events, a gesture needs to set a propagation phase through the gtk:event-controller-propagation-phase function.

In the capture phase, events are propagated from the toplevel down to the target widget, and gestures that are attached to containers above the widget get a chance to interact with the event before it reaches the target.

In the bubble phase, events are propagated up from the target widget to the toplevel, and gestures that are attached to containers above the widget get a chance to interact with events that have not been handled yet.

States of a sequence
Whenever input interaction happens, a single event may trigger a cascade of gestures, both across the parents of the widget receiving the event and in parallel within an individual widget. It is a responsibility of the widgets using those gestures to set the state of touch sequences accordingly in order to enable cooperation of gestures around the event sequences triggering those.

Within a widget, gestures can be grouped through the gtk:gesture-group function, grouped gestures synchronize the state of sequences, so calling the gtk:gesture-set-state function on one will effectively propagate the state throughout the group.

By default, all sequences start out in the :none state, sequences in this state trigger the gesture event handler, but event propagation will continue unstopped by gestures.

If a sequence enters into the :denied state, the gesture group will effectively ignore the sequence, letting events go unstopped through the gesture, but the "slot" will still remain occupied while the touch is active.

If a sequence enters in the :claimed state, the gesture group will grab all interaction on the sequence, by:
  • Setting the same sequence to :denied on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain.
  • Calling the "cancel" signal on every gesture in widgets underneath in the propagation chain.
  • Stopping event propagation after the gesture group handles the event.
Note: if a sequence is set early to :claimed on :touch-begin/:button-press events, so those events are captured before reaching the event widget, this implies :phase-capture, one similar event will emulated if the sequence changes to :denied. This way event coherence is preserved before event propagation is unstopped again.

Sequence states can not be changed freely, see the gtk:gesture-set-state function to know about the possible lifetimes of a gdk:event-sequence instance.

Touchpad gestures
On the platforms that support it, the gtk:gesture object will handle transparently touchpad gesture events. The only precautions users of the gtk:gesture object should do to enable this support are:
  • If the gesture has the :none value of the gtk:propagation-phase enumeration, ensuring events of type :touchpad-swipe and :touchpad-pinch are handled by the gtk:gesture object.
Signal Details:
The "begin" signal
lambda (gesture sequence)    :run-last      
gesture
The gtk:gesture object which received the signal.
sequence
The gdk:event-sequence event that made the gesture to be recognized.
The signal is emitted when the gesture is recognized. This means the number of touch sequences matches n-points Note: These conditions may also happen when an extra touch, for example, a third touch on a 2-touches gesture, is lifted, in that situation sequence will not pertain to the current set of active touches, so do not rely on this being true.
The "cancel" signal
lambda (gesture sequence)    :run-last      
gesture
The gtk:gesture object which received the signal.
sequence
The gdk:event-sequence instance that was cancelled.
The signal is emitted whenever a sequence is cancelled. This usually happens on active touches when the gtk:event-controller-reset function is called on gesture, manually, due to grabs ..., or the individual sequence was claimed by controllers of the parent widgets, see the gtk:gesture-set-sequence-state) function. The gesture argument must forget everything about sequence as a reaction to the signal.
The "end" signal
lambda (gesture sequence)    :run-last      
gesture
The gtk:gesture object which received the signal.
sequence
The gdk:event-sequence instance that made gesture recognition to finish.
The signal is emitted when gesture either stopped recognizing the event sequences as something to be handled, or the number of touch sequences became higher or lower than the n-points value. Note: The sequence argument might not pertain to the group of sequences that were previously triggering recognition on gesture, that is a just pressed touch sequence that exceeds the n-points value. This situation may be detected by checking through the gtk:gesture-handles-sequence function.
The "sequence-state-changed" signal
lambda (gesture sequence state)    :run-last      
gesture
The gtk:gesture object which received the signal.
sequence
The gdk:event-sequence instance that was cancelled.
state
The new gtk:event-sequence-state value.
The signal is emitted whenever a sequence state changes. See the gtk:gesture-sequence-state function to know more about the expectable sequence lifetimes.
The "update" signal
lambda (gesture sequence)    :run-last      
gesture
The gtk:gesture object which received the signal.
sequence
The gdk:event-sequence instance that was updated.
The signal is emitted whenever an event is handled while the gesture is recognized. The sequence argument is guaranteed to pertain to the set of active touches.
See also:
2024-7-27
Accessor gtk:gesture-n-points (object)
Syntax:
(gtk:gesture-n-points object) => n-points
Arguments:
object -- a gtk:gesture object
n-points -- an integer with the number of touch points
Details:
Accessor of the n-points slot of the gtk:gesture class. The number of touch points that trigger recognition on this gesture.
See also:
2024-7-27
Function gtk:gesture-device (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
The gdk:device object, or nil.
Details:
Returns the logical gdk:device object that is currently operating on gesture, or nil if the gesture is not being interacted.
See also:
2024-7-27
Function gtk:gesture-is-active (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
True if gesture is active.
Details:
Returns true if the gesture is currently active. A gesture is active meanwhile there are touch sequences interacting with the gesture.
See also:
2024-7-27
Function gtk:gesture-is-recognized (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
True if gesture is recognized.
Details:
Returns true if the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required by the gesture.
See also:
2024-7-27
Function gtk:gesture-sequence-state (gesture sequence)
Syntax:
(gtk:gesture-sequence-state gesture sequence) => state
(setf (gtk:gesture-sequence-state gesture sequence) state)
Arguments:
gesture -- a gtk:gesture object
sequence -- a gdk:event-sequence instance
state -- a gtk:event-sequence-state value
Details:
The gtk:gesture-sequence-state function returns the sequence state, as seen by the gesture. The (setf gtk:gesture-sequence-state) function sets the state of sequence in the gesture.
Warning:
The (setf gtk:gesture-sequence-state) function is deprecated since 4.10. Use the gtk:gesture-set-state function.
See also:
#2024-7-27
Function gtk:gesture-set-state (gesture state)
Arguments:
gesture -- a gtk:gesture object
state -- a gtk:event-sequence-state value
Returns:
True if the state of at least one sequence was changed successfully.
Details:
Sets the state of all sequences that the gesture is currently interacting with. Sequences start in :none state, and whenever they change state, they can never go back to that state. Likewise, sequences in :denied state cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four:
  • None
  • None → Denied
  • None → Claimed
  • None → Claimed → Denied
Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a "begin" signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be:
static void
first_gesture_begin_cb (GtkGesture       *first_gesture,
                        GdkEventSequence *sequence,
                        gpointer          user_data)
{
  gtk_gesture_set_sequence_state (first_gesture,
                                  sequence, GTK_EVENT_SEQUENCE_CLAIMED);
  gtk_gesture_set_sequence_state (second_gesture,
                                  sequence, GTK_EVENT_SEQUENCE_DENIED);
}

static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); }
If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event.
See also:
#2024-7-27
Function gtk:gesture-sequences (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
The list of gdk:event-sequence instances.
Details:
Returns the list of gdk:event-sequence instances currently being interpreted by gesture.
See also:
2024-7-27
Function gtk:gesture-handles-sequence (gesture sequence)
Arguments:
gesture -- a gtk:gesture object
sequence -- a gdk:event-sequence instance, or nil
Returns:
True if gesture is handling sequence, false otherwise.
Details:
Returns true if gesture is currently handling events corresponding to sequence.
See also:
#2024-7-27
Function gtk:gesture-last-updated-sequence (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
The last updated gdk:event-sequence instance.
Details:
Returns the gdk:event-sequence instance that was last updated on gesture.
See also:
#2024-7-27
Function gtk:gesture-last-event (gesture sequence)
Arguments:
gesture -- a gtk:gesture object
sequence -- a gdk:event-sequence instance
Returns:
The last gdk:event instance from sequence.
Details:
Returns the last event that was processed for sequence. Note that the returned pointer is only valid as long as the sequence is still interpreted by the gesture. If in doubt, you should make a copy of the event.
See also:
#2024-7-27
Function gtk:gesture-point (gesture sequence)
Arguments:
gesture -- a gtk:gesture object
sequence -- a gdk:event-sequence instance, or nil for pointer events
Returns:
x -- a double float with the x axis of the sequence coordinates
y -- a double float with the y axis of the sequence coordinates
Details:
If sequence is currently being interpreted by gesture, this function returns x and y with the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation.
See also:
#2024-7-27
Function gtk:gesture-bounding-box (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
The gdk:rectangle instance with the bounding box containing all active touches.
Details:
If there are touch sequences being currently handled by gesture, this function returns the bounding box containing all active touches. Otherwise, false will be returned.

Note: This function will yield unexpected results on touchpad gestures. Since there is no correlation between physical and pixel distances, these will look as if constrained in an infinitely small area, rect width and height will thus be 0 regardless of the number of touchpoints.
See also:
#2024-7-27
Function gtk:gesture-bounding-box-center (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
x -- a double float with the x coordinate for the bounding box center
y -- a double float with the y coordinate for the bounding box center
Details:
If there are touch sequences being currently handled by gesture, this function returns in x and y the center of the bounding box containing all active touches. Otherwise, false will be returned.
See also:
#2024-7-27
Function gtk:gesture-group (group gesture)
Arguments:
group -- a gtk:gesture object to group gesture with
gesture -- a gtk:gesture object
Details:
Adds gesture to the same group than group. Gestures are by default isolated in their own groups. Both gestures must have been added to the same widget before they can be grouped.

When gestures are grouped, the state of the gdk:event-sequence instances is kept in sync for all of those, so calling the gtk:gesture-sequence-state function, on one will transfer the same value to the others.

Groups also perform an "implicit grabbing" of sequences, if a gdk:event-sequence instance is set to :claimed on one group, every other gesture group attached to the same gtk:widget object will switch the state for that sequence to :denied.
See also:
#2024-7-27
Function gtk:gesture-ungroup (gesture)
Arguments:
gesture -- a gtk:gesture object
Details:
Separates gesture into an isolated group.
See also:
#2024-7-27
Function gtk:gesture-get-group (gesture)
Arguments:
gesture -- a gtk:gesture object
Returns:
The list of all gtk:gesture objects in the group of gesture.
Details:
Returns all gestures in the group of gesture.
See also:
#2024-7-27
Function gtk:gesture-is-grouped-with (gesture other)
Arguments:
gesture -- a gtk:gesture object
other -- another gtk:gesture object
Returns:
The boolean whether the gestures are grouped.
Details:
Returns true if both gestures pertain to the same group.
See also:
#2024-7-27

GtkGestureSingle

Class gtk:gesture-single
Superclasses:
gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
button
The button property of type :uint (Read / Write)
Mouse button number to listen to, or 0 to listen for any button.
Default value: 1
exclusive
The exclusive property of type :boolean (Read / Write)
Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events.
Default value: false
touch-only
The touch-only property of type :boolean (Read / Write)
Whether the gesture handles only touch events.
Default value: false
Slot Access Functions:
Details:
The gtk:gesture-single class is a gtk:gesture implementation optimized for single-touch and mouse gestures. Under interaction, these gestures stick to the first interacting sequence, which is accessible through the gtk:gesture-single-current-sequence function while the gesture is being interacted with.

By default gestures react to both the button primary and touch events. The gtk:gesture-single-touch-only function can be used to change the touch behavior. Callers may also specify a different mouse button number to interact with through the gtk:gesture-single-button function, or react to any mouse button by setting 0. While the gesture is active, the button being currently pressed can be known through the gtk:gesture-single-current-button function.
See also:
2024-2-19
Accessor gtk:gesture-single-button (object)
Syntax:
(gtk:gesture-single-button object) => button
(setf (gtk:gesture-single-button object) button)
Arguments:
object -- a gtk:gesture-single object
button -- an unsigned integer with the button number to listen to, or 0 for any button
Details:
Accessor of the button slot of the gtk:gesture-single class. The gtk:gesture-single-button function returns the button number gesture listens for, or 0 to listen for any button. The (setf gtk:gesture-single-button) function sets the button number. If non-0, every button press from a different button number will be ignored. Touch events implicitly match with button 1.
See also:
2024-2-19
Accessor gtk:gesture-single-exclusive (object)
Syntax:
(gtk:gesture-single-exclusive object) => exclusive
(setf (gtk:gesture-single-exclusive object) exclusive)
Arguments:
object -- a gtk:gesture-single object
exclusive -- true to make the gesture exclusive
Details:
Accessor of the exclusive slot of the gtk:gesture-single class. The gtk:gesture-single-exclusive function gets whether the gesture is exclusive. The (setf gtk:gesture-single-exclusive) function sets whether the gesture is exclusive. An exclusive gesture will only handle pointer and "pointer emulated" touch events, so at any given time, there is only one sequence able to interact with those.
See also:
2024-2-19
Accessor gtk:gesture-single-touch-only (object)
Syntax:
(gtk:gesture-single-touch-only object) => touch-only
(setf (gtk:gesture-single-touch-only object) touch-only)
Arguments:
object -- a gtk:gesture-single object
touch-only -- a boolean whether gesture handles only touch events
Details:
Accessor of the touch-only slot of the gtk:gesture-single class. The gtk:gesture-single-touch-only function returns true if the gesture is only triggered by touch events. The (setf gtk:gesture-single-touch-only) function sets whether the gesture is only triggered by touch events. If the touch-only argument is true, the gesture will only handle events of type :touch-begin, :touch-update or :touch-end. If false, mouse events will be handled too.
See also:
2024-2-19
Function gtk:gesture-single-current-button (gesture)
Arguments:
gesture -- a gtk:gesture-single object
Returns:
The unsigned integer with the current button number.
Details:
Returns the button number currently interacting with gesture, or 0 if there is none.
See also:
2024-2-19
Function gtk:gesture-single-current-sequence (gesture)
Arguments:
gesture -- a gtk:gesture-single object
Returns:
The current gdk:event-sequence instance.
Details:
Returns the event sequence currently interacting with the gesture. This is only meaningful if the gtk:gesture-is-active function returns true.
See also:
2024-2-19

GtkGestureDrag

Class gtk:gesture-drag
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:gesture-drag class is a gtk:gesture implementation that recognizes drag operations. The drag operation itself can be tracked throught the "drag-begin", "drag-update" and "drag-end" signals, or the relevant coordinates be extracted through the gtk:gesture-drag-offset and gtk:gesture-drag-start-point functions.
Signal Details:
The "drag-begin" signal
lambda (gesture xstart ystart)    :run-last      
gesture
The gtk:gesture-drag object which received the signal.
xstart
The double float with the x coordinate, relative to the widget allocation.
ystart
The double float with the y coordinate, relative to the widget allocation.
The signal is emitted whenever dragging starts.
The "drag-end" signal
lambda (gesture xoffset yoffset)    :run-last      
gesture
The gtk:gesture-drag object which received the signal.
xoffset
The double float with the x offset, relative to the start point.
yoffset
The double float with the y offset, relative to the start point.
The signal is emitted whenever the dragging is finished.
The "drag-update" signal
lambda (gesture xoffset yoffset)    :run-last      
gesture
The gtk:gesture-drag object which received the signal.
xoffset
The double float with the x offset, relative to the start point.
yoffset
The double float with the y offset, relative to the start point.
The signal is emitted whenever the dragging point moves.
See also:
2024-4-29
Function gtk:gesture-drag-new ()
Returns:
The newly created gtk:gesture-drag object.
Details:
Returns a newly created gesture that recognizes drags.
See also:
2024-4-29
Function gtk:gesture-drag-start-point (gesture)
Arguments:
gesture -- a gtk:gesture-drag object
Returns:
x -- a double float with the x coordinate for the drag start point
y -- a double float with the y coordinate for the drag start point
Details:
If the gesture is active, this function returns the drag start coordinates, in widget-relative coordinates, otherwise nil is returned.
See also:
2024-2-19
Function gtk:gesture-drag-offset (gesture)
Arguments:
gesture -- a gtk:gesture-drag object
Returns:
x -- a double float with the x offset for the current point
y -- a double float with the y offset for the current point
Details:
If the gesture is active, this function returns the coordinates of the current point, as an offset to the starting drag point, otherwise nil is returned.
See also:
2024-2-19

GtkGestureLongPress

Class gtk:gesture-long-press
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
delay-factor
The delay-factor property of type :double (Read / Write)
Factor by which to modify the default timeout.
Allowed values: [0.5d0, 2.0d0]
Default value: 1.0d0
Returned by:
Slot Access Functions:
Details:
The gtk:gesture-long-press object is a gesture for long presses. This gesture is also known as "Press and Hold".

When the timeout is exceeded, the gesture is triggering the "pressed" signal. If the touchpoint is lifted before the timeout passes, or if it drifts too far of the initial press point, the "cancelled" signal will be emitted. How long the timeout is before the "pressed" signal gets emitted is determined by the gtk-long-press-time setting. It can be modified by the delay-factor property.
Signal Details:
The "cancelled" signal
lambda (gesture)    :run-last      
gesture
The gtk:gesture-long-press object which received the signal.
The signal is emitted whenever a press moved too far, or was released before the "pressed" signal happened.
The "pressed" signal
lambda (gesture x y)    :run-last      
gesture
The gtk:gesture-long-press object which received the signal.
x
The double float with the x coordinate where the press happened, relative to the widget allocation.
y
The double float with the y coordinate where the press happened, relative to the widget allocation.
The signal is emitted whenever a press goes unmoved/unreleased longer than what the GTK defaults tell.
See also:
2024-2-19
Accessor gtk:gesture-long-press-delay-factor (object)
Syntax:
(gtk:gesture-long-press-delay-factor object) => factor
(setf (gtk:gesture-long-press-delay-factor object) factor)
Arguments:
object -- a gtk:gesture-long-press object
factor -- a double float with the factor by which to modify the default timeout
Details:
Accessor of the delay-factor slot of the gtk:gesture-long-press class.
See also:
2024-2-19
Function gtk:gesture-long-press-new ()
Returns:
The newly created gtk:gesture-long-press object.
Details:
Returns a newly created gesture that recognizes long presses.
See also:
2024-2-19

GtkGestureClick

Class gtk:gesture-click
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:gesture-click class is a gtk:gesture implementation for clicks. It is able to recognize multiple clicks on a nearby zone, which can be listened for through the "pressed" signal. Whenever time or distance between clicks exceed the GTK defaults, the "stopped" signal is emitted, and the click counter is reset.
Signal Details:
The "pressed" signal
lambda (gesture n x y)    :run-last      
gesture
The gtk:gesture-click object which received the signal.
n
The integer of how many touch/button press happened with this one.
x
The double float with the x coordinate, in widget allocation coordinates.
y
The double float with the y coordinate, in widget allocation coordinates.
The signal is emitted whenever a button or touch press happens.
The "released" signal
lambda (gesture n x y)    :run-last      
gesture
The gtk:gesture-click object which received the signal.
n
The integer with the number of presses that is paired with this release.
x
The double float with the x coordinate, in widget allocation coordinates.
y
The double float with the y coordinate, in widget allocation coordinates.
The signal is emitted when a button or touch is released. The n argument will report the number of press that is paired to this event, note that the "stopped" signal may have been emitted between the press and its release, n will only start over at the next press.
The "stopped" signal
lambda (gesture)    :run-last      
gesture
The gtk:gesture-click object which received the signal.
The signal is emitted whenever any time/distance threshold has been exceeded.
The "unpaired-release" signal
lambda (gesture x y button sequence)    :run-last      
gesture
The gtk:gesture-click object which received the signal.
x
The double float with the x coordinate of the event.
y
The double float with the y coordinate of the event.
button
The unsigned integer with the button being released.
sequence
The gdk:event-sequence instance being released.
The signal is emitted whenever the gesture receives a release event that had no previous corresponding press. Due to implicit grabs, this can only happen on situations where input is grabbed elsewhere mid-press or the pressed widget voluntarily relinquishes its implicit grab.
See also:
2025-2-22
Function gtk:gesture-click-new ()
Returns:
The newly created gtk:gesture-click object.
Details:
Returns a newly created gesture that recognizes single and multiple presses.
See also:
2025-2-22

GtkGesturePan

GEnum gtk:pan-direction
Declaration:
(gobject:define-genum "GtkPanDirection" pan-direction
  (:export t
   :type-initializer "gtk_pan_direction_get_type")
  :left
  :right
  :up
  :down)  
Values:
:left
Panned towards the left.
:right
Panned towards the right.
:up
Panned upwards.
:down
Panned downwards.
Details:
Describes the panning direction of a gtk:gesture-pan object.
See also:
2024-2-19
Class gtk:gesture-pan
Superclasses:
Documented Subclasses:
None
Direct Slots:
orientation
The orientation property of type gtk:orientation (Read / Write)
The expected orientation of pan gestures.
Default value: :horizontal
Returned by:
Slot Access Functions:
Details:
The gtk:gesture-pan class is a gtk:gesture implementation for pan gestures. These are drags that are locked to happen along one axis.

The axis that a gtk:gesture-pan object handles is defined at construct time, and can be changed through the gtk:gesture-pan-orientation function. When the gesture starts to be recognized, the gtk:gesture-pan object will attempt to determine as early as possible whether the sequence is moving in the expected direction, and denying the sequence if this does not happen. Once a panning gesture along the expected axis is recognized, the "pan" signal will be emitted as input events are received, containing the offset in the given axis.
Signal Details:
The "pan" signal
lambda (gesture direction offset)    :run-last    
gesture
The gtk:gesture-pan object which received the signal.
direction
The current gtk:pan-direction value of the pan gesture.
offset
The double float with the offset along the gesture orientation.
The signal is emitted once a panning gesture along the expected axis is detected.
See also:
2024-2-19
Accessor gtk:gesture-pan-orientation (object)
Syntax:
(gtk:gesture-pan-orientation object) => orientation
(setf (gtk:gesture-pan-orientation object) orientation)
Arguments:
object -- a gtk:gesture object
orientation -- a gtk:orientation value
Details:
Accessor of the orientation slot of the gtk:gesture-pan class. The gtk:gesture-pan-orientation function returns the orientation of the pan gestures that this gesture expects. The (setf gtk:gesture-pan-orientation) function sets the orientation.
See also:
2024-2-19
Function gtk:gesture-pan-new (orientation)
Arguments:
orientation -- a gtk:orientation value
Returns:
The newly created gtk:gesture-pan object.
Details:
Returns a newly created gesture that recognizes pan gestures.
See also:
2024-2-19

GtkGestureSwipe

Class gtk:gesture-swipe
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:gesture-swipe class is a gtk:gesture implementation for swipe gestures. After a press/move/.../move/release sequence happens, the "swipe" signal will be emitted, providing the velocity and directionality of the sequence at the time it was lifted.

If the velocity is desired in intermediate points, the gtk:gesture-swipe-velocity function can be called in a "update" signal handler for the gdk:frame-clock object. All velocities are reported in pixels/sec units.
Signal Details:
The "swipe" signal
lambda (gesture xvel yvel)    :run-last      
gesture
The gtk:gesture-swipe object which received the signal.
xvel
The double float with the velocity in the x axis, in pixels/sec.
yvel
The double float with the velocity in the y axis, in pixels/sec.
The signal is emitted when the recognized gesture is finished, velocity and direction are a product of previously recorded events.
See also:
2024-7-27
Function gtk:gesture-swipe-new ()
Returns:
The newly created gtk:gesture-swipe object.
Details:
Returns a newly created gesture that recognizes swipes.
See also:
2024-2-19
Function gtk:gesture-swipe-velocity (gesture)
Arguments:
gesture -- a gtk:gesture-swipe object
Returns:
xvel -- a double float with the velocity in the x axis, in pixels/sec.
yvel -- a double float with the velocity in the y axis, in pixels/sec.
Details:
If the gesture is recognized, this function returns the recorded velocity, as per the last event(s) processed, otherwise nil is returned.
See also:
2024-2-19

GtkGestureRotate

Class gtk:gesture-rotate
Superclasses:
gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:gesture-rotate class is a gtk:gesture implementation for 2-finger rotations. Whenever the angle between both handled sequences changes, the "angle-changed" signal is emitted.
Signal Details:
The "angle-changed" signal
lambda (gesture angle delta)    :run-first      
gesture
The gtk:gesture-rotate object which received the signal.
angle
The double float with the current angle in radians.
delta
The double float with the difference with the starting angle, in radians.
The signal is emitted when the angle between both tracked points changes.
See also:
2024-7-27
Function gtk:gesture-rotate-new ()
Returns:
The newly created gtk:gesture-rotate object.
Details:
Returns a newly created gesture that recognizes 2-touch rotation gestures.
See also:
2024-2-19
Function gtk:gesture-rotate-angle-delta (gesture)
Arguments:
gesture -- a gtk:gesture-rotate object
Returns:
The double float with the angle delta in radians.
Details:
If the gesture is active, this function returns the angle difference in radians since the gesture was first recognized. If gesture is not active, 0.0d0 is returned.
See also:
2024-2-19

GtkGestureZoom

Class gtk:gesture-zoom
Superclasses:
gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:gesture-zoom class is a gtk:gesture implementation for 2-finger pinch/zoom gestures. Whenever the distance between both tracked sequences changes, the "scale-changed" signal is emitted to report the scale factor.
Signal Details:
The "scale-changed" signal
lambda (gesture scale)    :run-first      
gesture
The gtk:gesture-zoom object on which the signal is emitted.
scale
The double float with the scale delta, taking the initial state as 1:1.
The signal is emitted whenever the distance between both tracked sequences changes.
See also:
2024-7-27
Function gtk:gesture-zoom-new ()
Returns:
The newly created gtk:gesture-zoom object.
Details:
Returns a newly created gesture that recognizes pinch/zoom gestures.
See also:
2024-7-27
Function gtk:gesture-zoom-scale-delta (gesture)
Arguments:
widget -- a gtk:gesture-zoom object
Returns:
The double float with the scale delta.
Details:
If the gesture is active, this function returns the zooming difference since the gesture was recognized, hence the starting point is considered 1:1. If the gesture is not active, 1.0d0 is returned.
See also:
2024-7-27

GtkGestureStylus

Class gtk:gesture-stylus
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
stylus-only
The stylus-only property of type :boolean (Read / Write / Construct)
If this gesture should exclusively react to stylus input devices. Since 4.10
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:gesture-stylus class is a gtk:gesture implementation specific to stylus input. The provided signals just provide the basic information of the stylus events.
Signal Details:
The "down" signal
lambda (gesture x y)    :run-last      
gesture
The gtk:gesture-stylus object on which the signal is emitted.
x
The double float with the x coordinate of the stylus event.
y
The double float with the y coordinate of the stylus event.
The "motion" signal
lambda (gesture x y)    :run-last      
gesture
The gtk:gesture-stylus object on which the signal is emitted.
x
The double float with the x coordinate of the stylus event.
y
The double float with the y coordinate of the stylus event.
The "proximity" signal
lambda (gesture x y)    :run-last      
gesture
The gtk:gesture-stylus object on which the signal is emitted.
x
The double float with the x coordinate of the stylus event.
y
The double float with the y coordinate of the stylus event.
The "up" signal
lambda (gesture x y)    :run-last      
gesture
The gtk:gesture-stylus object on which the signal is emitted.
x
The double float with the x coordinate of the stylus event.
y
The double float with the y coordinate of the stylus event.
See also:
2024-2-21
Accessor gtk:gesture-stylus-stylus-only (object)
Syntax:
(gtk:gesture-stylus-only object) => setting
(setf (gtk:gesture-stylus-only object) setting)
Arguments:
object -- a gtk:gesture-stylus object
setting -- a boolean whether the gesture is used exclusivly for stylus events
Details:
Accessor of the stylus-only slot of the gtk:gesture-stylus class. The gtk:gesture-stylus-stylus-only function checks whether the gesture handle events from stylus input devices, otherwise it will handle events from any pointing device. The (setf gtk:gesture-stylus-stylus-only) function sets the state of the property.

Since 4.10
See also:
2024-2-21
Function gtk:gesture-stylus-new ()
Returns:
The newly created gtk:gesture-stylus object.
Details:
Creates a new stylus gesture.
See also:
2024-2-21
Function gtk:gesture-stylus-axis (gesture axis)
Arguments:
gesture -- a gtk:gesture-stylus object
axis -- a gdk:axis-use value with the requested device axis
Returns:
The double float with the current value for the axis.
Details:
Returns the current value for the requested axis. This function must be called from either the "down", "motion", "up" or "proximity" signals.
See also:
2024-2-21
Function gtk:gesture-stylus-device-tool (gesture)
Arguments:
gesture -- a gtk:gesture-stylus object
Returns:
The current gdk:device-tool object.
Details:
Returns the device tool currently driving input through this gesture. This function must be called from either the "down", "motion", "up" or "proximity" signal handlers.
See also:
2024-2-21

GtkPadController

GEnum gtk:pad-action-type
Declaration:
(gobject:define-genum "GtkPadActionType" pad-action-type
  (:export t
   :type-initializer "gtk_pad_action_type_get_type")
  :button
  :ring
  :strip)  
Values:
:button
Action is triggered by a pad button.
:ring
Action is triggered by a pad ring.
:strip
Action is triggered by a pad strip.
Details:
The type of a pad action.
See also:
2025-2-23
Class gtk:pad-controller
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
action-group
The action-group property of type g:action-group (Read / Write / Construct Only)
The action group to launch actions from.
pad
The pad property of type gdk:device (Read / Write / Construct Only)
The pad device to control.
Returned by:
Slot Access Functions:
Details:
The gtk:pad-controller object is an event controller for the pads found in drawing tablets. Pads are the collection of buttons and tactile sensors often found around the stylus-sensitive area.

These buttons and sensors have no implicit meaning, and by default they perform no action, this event controller is provided to map those to g:action objects, thus letting the application give those a more semantic meaning.

Buttons and sensors are not constrained to triggering a single action, some :tablet-pad devices feature multiple "modes", all these input elements have one current mode, which may determine the final action being triggered. Pad devices often divide buttons and sensors into groups, all elements in a group share the same current mode, but different groups may have different modes. See the gdk:device-pad-n-groups and gdk:device-pad-group-n-modes functions.

Each of the actions that a given button/strip/ring performs for a given mode is defined by the arguments of the gtk:pad-controller-set-action function, it contains an action name that will be looked up in the given g:action-group instance and activated whenever the specified input element and mode are triggered.
Examples:
A simple example of gtk:pad-controller usage, assigning button 1 in all modes and pad devices to an "invert-selection" action:
GtkPadActionEntry *pad_actions = {
  { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection",
                                  "pad-actions.invert-selection" },
  ...
};

... action_group = g_simple_action_group_new (); action = g_simple_action_new ("pad-actions.invert-selection", NULL); g_signal_connect (action, "activate", on_invert_selection_activated, NULL); g_action_map_add_action (G_ACTION_MAP (action_group), action); ... pad_controller = gtk_pad_controller_new (action_group, NULL);
The actions belonging to rings/strips will be activated with a parameter of "d" variant type bearing the value of the given axis, it is required that those are made stateful and accepting this g:variant-type type.
See also:
2025-2-23
Accessor gtk:pad-controller-action-group (object)
Syntax:
(gtk:pad-controller-action-group object) => group
(setf (gtk:pad-controller-action-group object) group)
Arguments:
object -- a gtk:pad-controller object
group -- a g:action-group instance
Details:
Accessor of the action-group slot of the gtk:pad-controller class.
See also:
2025-2-23
Accessor gtk:pad-controller-pad (object)
Syntax:
(gtk:pad-controller-pad object) => pad
(setf (gtk:pad-controller-pad object) pad)
Arguments:
object -- a gtk:pad-controller object
pad -- a gdk:device object
Details:
Accessor of the pad slot of the gtk:pad-controller class.
See also:
2025-2-23
Function gtk:pad-controller-new (group &optional pad)
Arguments:
group -- a g:action-group instance to trigger actions from
pad -- a gdk:device object of :tablet-pad type of the gdk:input-source enumeration, or the nil default value to handle all pads
Returns:
The newly created gtk:pad-controller object.
Details:
Creates a new gtk:pad-controller object that will associate events from pad to actions. A NIL pad may be provided so the controller manages all pad devices generically, it is discouraged to mix gtk:pad-controller objects with NIL and non-NIL pad arguments on the same toplevel window, as execution order is not guaranteed.

The gtk:pad-controller object is created with no mapped actions. In order to map pad events to actions, use the gtk:pad-controller-set-action-entries or gtk:pad-controller-set-action functions.

Be aware that pad events will only be delivered to gtk:window widgets so adding a pad controller to any other type of widget will not have an effect.
See also:
2025-2-23
Function gtk:pad-controller-set-action-entries (controller entries)
Arguments:
controller -- a gtk:pad-controller object
entries -- a '((type1 index1 mode1 label1 name1) ...) list with the action entries to set on controller
Details:
This is a convenience function to add a group of action entries on the pad controller. Each action entry in the list of action entries has the '(type index mode label name) parameters. See the gtk:pad-controller-set-action function for the documentation of the action entry parameters.
See also:
2025-2-23
Function gtk:pad-controller-set-action (controller type index mode label name)
Arguments:
controller -- a gtk:pad-controller object
type -- a gtk:pad-action-type value for the pad feature that will trigger the action
index -- an integer for the 0-indexed button/ring/strip number that will trigger the action
mode -- an integer for the mode that will trigger the action, or -1 for all modes
label -- a string for the Human readable description of the action, the string should be deemed user visible
name -- a string for the action name that will be activated in the g:action-group instance
Details:
Adds an individual action to controller. The action will only be activated if the given button/ring/strip number in index is interacted while the current mode is mode. The -1 value may be used for simple cases, so the action is triggered on all modes.

The given label should be considered user visible, so internationalization rules apply. Some windowing systems may be able to use those for user feedback.
See also:
2025-2-23

GtkShortcutController

GEnum gtk:shortcut-scope
Declaration:
(gobject:define-genum "GtkShortcutScope" shortcut-scope
  (:export t
   :type-initializer "gtk_shortcut_scope_get_type")
  :local
  :managed
  :global)  
Values:
:local
Shortcuts are handled inside the widget the controller belongs to.
:managed
Shortcuts are handled by the first ancestor that is a gtk:shortcut-manager object.
:global
Shortcuts are handled by the root widget.
Details:
Describes where gtk:shortcut objects added to the gtk:shortcut-controller object get handled.
See also:
2023-7-23
Class gtk:shortcut-controller
Superclasses:
gtk:event-controller, gtk:buildable, gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items. Since 4.8
mnemonic-modifiers
The mnemonic-modifiers property of type gdk:modifier-type (Read / Write)
The modifiers that need to be pressed to allow mnemonics activation.
Default value: :alt-mask
model
The model property of type g:list-model (Write / Construct Only)
The list model to take shortcuts from.
n-items
The n-items property of type :uint (Read)
The number of items in the list model. Since 4.8
Default value: 0
scope
The scope property of type gtk:shortcut-scope (Read / Write)
What scope the shortcuts will be handled in.
Default value: :local
Returned by:
Slot Access Functions:
Details:
The gtk:shortcut-controller class is an event controller that manages shortcuts. Most common shortcuts are using this controller implicitly, for example, by adding a mnemonic underline to a gtk:label widget, or by installing a key binding using the gtk:widget-class-add-binding function, or by adding accelerators to global actions using the gtk:application-accels-for-action function. But it is possible to create your own shortcut controller, and add shortcuts to it.

The gtk:shortcut-controller class implements the g:list-model interface for querying the shortcuts that have been added to it.

GtkShortcutController as a GtkBuildable
The gtk:shortcut-controller object can be created in UI files to set up shortcuts in the same place as the widgets. An example of a UI definition fragment with a gtk:shortcut-controller object:
<object class='GtkButton'>
  <child>
    <object class='GtkShortcutController'>
      <property name='scope'>managed</property>
      <child>
        <object class='GtkShortcut'>
          <property name='trigger'>&lt;Control&gt;k</property>
          <property name='action'>activate</property>
        </object>
      </child>
    </object>
  </child>
</object>  
This example creates a gtk:activate-action object for triggering the activate signal of the gtk:button widget. See the gtk:shortcut-action-parse-string function for the syntax for other kinds of gtk:shortcut-action objects. See the gtk:shortcut-trigger-parse-string function to learn more about the syntax for triggers.
See also:
2023-7-23
Accessor gtk:shortcut-controller-item-type (object)
Syntax:
(gtk:shortcut-controller-item-type object) => gtype
Arguments:
object -- a gtk:shortcut-controller object
gtype -- a g:type-t item type ID
Details:
Accessor of the item-type slot of the gtk:shortcut-controller class.

Since 4.8
See also:
2023-7-23
Accessor gtk:shortcut-controller-mnemonic-modifiers (object)
Syntax:
(gtk:shortcut-controller-mnemonic-modifiers object) => modifiers
(setf (gtk:shortcut-controller-mnemonic-modifiers object) modifiers)
Arguments:
object -- a gtk:shortcut-controller object
modifiers -- a gdk:modifier-type value
Details:
Accessor of the mnemonic-modifiers slot of the gtk:shortcut-controller class. The gtk:shortcut-controller-mnemonic-modifiers function gets the mnemonics modifiers for when this controller activates its shortcuts. The (setf gtk:shortcut-controller-mnemonic-modifiers) function sets the controller to have the given modifiers.

The mnemonics modifiers determines which modifiers need to be pressed to allow activation of shortcuts with mnemonics triggers. GTK normally uses the Alt modifier for mnemonics, except in gtk:popover-menu widgets, where mnemonics can be triggered without any modifiers. It should be very rarely necessary to change this, and doing so is likely to interfere with other shortcuts.

This value is only relevant for local shortcut controllers. Global and managed shortcut controllers will have their shortcuts activated from other places which have their own modifiers for activating mnemonics.
See also:
2023-7-23
Accessor gtk:shortcut-controller-model (object)
Syntax:
(gtk:shortcut-controller-model object) => model
(setf (gtk:shortcut-controller-model object) model)
Arguments:
object -- a gtk:shortcut-controller object
model -- a g:list-model object
Details:
Accessor of the model slot of the gtk:shortcut-controller class. A list model to take shortcuts from.
See also:
2023-7-23
Accessor gtk:shortcut-controller-n-items (object)
Syntax:
(gtk:shortcut-controller-n-items object) => n-items
Arguments:
object -- a gtk:shortcut-controller object
n-items -- an unsigned integer with the number of items in the list model
Details:
Accessor of the n-items slot of the gtk:shortcut-controller class.

Since 4.8
See also:
2023-7-23
Accessor gtk:shortcut-controller-scope (object)
Syntax:
(gtk:shortcut-controller-scope object) => scope
(setf (gtk:shortcut-controller-scope object) scope)
Arguments:
object -- a gtk:shortcut-controller object
scope -- a gtk:shortcut-scope value
Details:
Accessor of the scope slot of the gtk:shortcut-controller class. The gtk:shortcut-controller-scope function gets the scope for when the controller activates its shortcuts. The (setf gtk:shortcut-controller-scope) function sets the controller to have the given scrope.

The scope allows shortcuts to be activated outside of the normal event propagation. In particular, it allows installing global keyboard shortcuts that can be activated even when a widget does not have focus.

With the :local value, shortcuts will only be activated when the widget has focus.
See also:
2023-7-23
Function gtk:shortcut-controller-new ()
Returns:
The newly created gtk:shortcut-controller object.
Details:
Creates a new shortcut controller.
See also:
2023-7-23
Function gtk:shortcut-controller-new-for-model (model)
Arguments:
model -- a g:list-model object containing shortcuts
Returns:
The newly created gtk:shortcut-controller object.
Details:
Creates a new shortcut controller that takes its shortcuts from the given list model. A controller created by this function does not let you add or remove individual shortcuts using the shortcut controller API, but you can change the contents of the model.
See also:
#2023-7-23
Function gtk:shortcut-controller-add-shortcut (controller shortcut)
Arguments:
controller -- a gtk:shortcut-controller object
shortcut -- a gtk:shortcut object to add
Details:
Adds a shortcut to the list of shortcuts handled by controller. If this controller uses an external shortcut list, this function does nothing.
See also:
2024-5-13
Function gtk:shortcut-controller-remove-shortcut (controller shortcut)
Arguments:
controller -- a gtk:shortcut-controller object
shortcut -- a gtk:shortcut object to remove
Details:
Removes a shortcut from the list of shortcuts handled by controller. If shortcut had not been added to controller or this controller uses an external shortcut list, this function does nothing.
See also:
#2023-7-23

Data exchange, Clipboards, Drag and Drop

GtkDragSource

Class gtk:drag-source
Superclasses:
gtk:gesture-single, gtk:gesture, gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
actions
The actions property of type gdk:drag-action (Read / Write)
The actions that are supported by drag operations from the source. Note that you must handle the "drag-end" signal if the actions include :move.
Default value: :copy
content
The content property of type gdk:content-provider (Read / Write)
The data that is offered by drag operations from this source, in the form of a gdk:content-provider object.
Returned by:
Slot Access Functions:
Details:
The gtk:drag-source object is an auxiliary object that is used to initiate Drag and Drop operations. It can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a gdk:content-provider object, the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using the gtk:widget-add-controller function.

Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, the gtk:drag-source object has "prepare" and "drag-begin" signals. The "prepare" signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with. The "drag-begin" signal is emitted after the gdk:drag object has been created, and can be used to set up the drag icon.

During the DND operation, the gtk:drag-source object emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case. When the supported actions include the :move value of the gdk:drag-action flags, you need to listen for the "drag-end" signal and delete the data after it has been transferred.
Signal Details:
The "drag-begin" signal
lambda (source drag)    :run-last      
source
The gtk:drag-source object.
drag
The gdk:drag object.
The signal is emitted on the drag source when a drag is started. It can be used to, for example, set a custom drag icon with the gtk:drag-source-set-icon function.
The "drag-cancel" signal
lambda (source drag reason)    :run-last      
source
The gtk:drag-source object.
drag
The gdk:drag object.
reason
The gdk:drag-cancel-reason value with the information on why the drag failed.
Returns
True if the failed drag operation has been already handled.
The signal is emitted on the drag source when a drag has failed. The signal handler may handle a failed drag operation based on the type of error. It should return true if the failure has been handled and the default "drag operation failed" animation should not be shown.
The "drag-end" signal
lambda (source drag delete)    :run-last      
source
The gtk:drag-source object.
drag
The gdk:drag object.
delete
True if the drag was performing :move, and the data should be deleted.
Returns
True if the failed drag operation has been already handled.
The signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in the "prepare" or "drag-begin" handler.
The "prepare" signal
lambda (source x y)    :run-last      
source
The gtk:drag-source object.
x
The double float with the x coordinate of the drag starting point.
y
The double float with the y coordinate of the drag starting point.
Returns
The gdk:content-provider object, or nil.
The signal is emitted when a drag is about to be initiated. It returns the gdk:content-provider object to use for the drag that is about to start. The default handler for this signal returns the value of the content property, so if you set up that property ahead of time, you do not need to connect to this signal.
2024-11-2
Accessor gtk:drag-source-actions (object)
Syntax:
(gtk:drag-source-actions object) => actions
(setf (gtk:drag-source-actions object) actions)
Arguments:
object -- a gtk:drag-source object
actions -- a gdk:drag-action value with the actions to offer
Details:
Accessor of the actions slot of the gtk:drag-source class. The gtk:drag-source-actions function gets the actions that are currently set on the gtk:drag-source object. The (setf gtk:drag-source-actions) function sets the actions.

During a DND operation, the actions are offered to potential drop targets. If actions include :move, you need to listen to the "drag-end" signal and handle the delete argument being true.

This function can be called before a drag is started, or in a handler for the "prepare" signal.
See also:
2024-11-2
Accessor gtk:drag-source-content (object)
Syntax:
(gtk:drag-source-content object) => content
(setf (gtk:drag-source-content object) content)
Arguments:
object -- a gtk:drag-source object
content -- a gdk:content-provider object of source, or nil
Details:
Accessor of the content slot of the gtk:drag-source class. The gtk:drag-source-content function gets the current content provider of a gtk:drag-source object. The (setf gtk:drag-source-content) function sets a content provider. When the data is requested in the cause of a DND operation, it will be obtained from the content provider.

This function can be called before a drag is started, or in a handler for the "prepare" signal. You may consider setting the content provider back to nil in a "drag-end" signal handler.
See also:
2024-11-2
Function gtk:drag-source-new ()
Returns:
The new gtk:drag-source object
Details:
Creates a new drag source.
See also:
2024-11-2
Function gtk:drag-source-set-icon (source paintable xhot yhot)
Arguments:
source -- a gtk:drag-source object
paintable -- a gdk:paintable object to use as icon, or nil
xhot -- an integer with the hotspot x coordinate on the icon
yhot -- an integer with the hotspot y coordinate on the icon
Details:
Sets a paintable to use as icon during DND operations. The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor. If paintable is nil, a default icon is used.

This function can be called before a drag is started, or in a "prepare" or "drag-begin" signal handler.
See also:
#2023-7-31
Function gtk:drag-source-drag-cancel (source)
Arguments:
source -- a gtk:drag-source object
Details:
Cancels a currently ongoing drag operation.
See also:
#2023-7-31
Function gtk:drag-source-drag (source)
Arguments:
source -- a gtk:drag-source object
Returns:
The gdk:drag object of the current drag operation, or nil.
Details:
Returns the underlying gdk:drag object for an ongoing drag.
See also:
#2023-7-31
Function gtk:drag-check-threshold (widget xstart ystart xcurrent ycurrent)
Arguments:
source -- a gtk:drag-source object
xstart -- an integer with the x coordinate of start of drag
ystart -- an integer with the y coordinate of start of drag
xcurrent -- an integer with the current x coordinate
ycurrent -- an integer with the current y coordinate
Returns:
True if the drag threshold has been passed.
Details:
Checks to see if a mouse drag starting at (xstart, ystart) and ending at (xcurrent, ycurrent) has passed the GTK drag threshold, and thus should trigger the beginning of a drag-and-drop operation.
See also:
#2023-7-31

GtkDragIcon

Class gtk:drag-icon
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The widget to display as drag icon.
Slot Access Functions:
Details:
The gtk:drag-icon widget is a gtk:root implementation with the sole purpose to serve as a drag icon during DND operations. A drag icon moves with the pointer during a drag operation and is destroyed when the drag ends.

To set up a drag icon and associate it with an ongoing drag operation, use the gtk:drag-icon-for-drag function to get the icon for a drag. You can then use it like any other widget and use the gtk:drag-icon-child function to set whatever widget should be used for the drag icon.

Keep in mind that drag icons do not allow user input.
2023-7-31
Accessor gtk:drag-icon-child (object)
Syntax:
(gtk:drag-icon-child object) => child
(setf (gtk:drag-icon-child object) child)
Arguments:
object -- a gtk:drag-icon widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:drag-icon class. The gtk:drag-icon-child function gets the widget currently used as drag icon. The (setf gtk:drag-icon-child) function sets the widget to display as the drag icon.
See also:
#2023-7-31
Function gtk:drag-icon-for-drag (drag)
Arguments:
drag -- a gdk:drag object
Returns:
The gtk:widget object with the drag icon.
Details:
Gets the drag icon in use with drag. If no drag icon exists yet, a new one will be created and shown.
See also:
#2023-7-31
Function gtk:drag-icon-set-from-paintable (drag paintable xhot yhot)
Arguments:
drag -- a gdk:drag object
paintable -- a gdk:paintable object to display
xhot -- an integer with the x coordinate of the hotspot
yhot -- an integer with the y coordinate of the hotspot
Details:
Creates a drag icon that shows paintable, and associates it with the drag operation. The hotspot position on the paintable is aligned with the hotspot of the cursor.
See also:
#2023-7-31
Function gtk:drag-icon-create-widget-for-value (value)
Arguments:
gvalue -- a g:value instance
Returns:
The new gtk:widget object for displaying gvalue as a drag icon.
Details:
Creates a widget that can be used as a drag icon for the given gvalue. Supported types include strings, gdk:rgba instances and gtk:text-buffer objects. If GTK does not know how to create a widget for a given value, it will return nil.

This method is used to set the default drag icon on drag and drop operations started by the gtk:drag-source object, so you do not need to set a drag icon using this function there.

See also:
#2023-7-31

GtkDropTarget

Class gtk:drop-target
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
actions
The actions property of type gdk:drag-action (Read / Write)
The actions that this drop target supports.
Default value: :none
current-drop
The current-drop property of type gdk:drop (Read)
The drop that is currently being performed. Since 4.4
drop
The drop property of type gdk:drop (Read)
The drop that is currently being performed. Deprecated 4.4
formats
The formats property of type gdk:content-formats (Read)
The content formats that determine the supported data formats.
preload
The preload property of type :boolean (Read / Write)
Whether the drop data should be preloaded when the pointer is only hovering over the widget but has not been released. Setting this property allows finer grained reaction to an ongoing drop at the cost of loading more data. The default value for this property is false to avoid downloading huge amounts of data by accident. For example, if somebody drags a full document of gigabytes of text from a text editor across a widget with a preloading drop target, this data will be downloaded, even if the data is ultimately dropped elsewhere. For a lot of data formats, the amount of data is very small, like the gdk:rgba color, so enabling this property does not hurt at all. And for local-only drag'n'drop operations, no data transfer is done, so enabling it there is free.
Default value: false
value
The value property of type g:value (Read)
The value for this drop operation or nil if the data has not been loaded yet or no drop operation is going on. Data may be available before the "current-drop" signal gets emitted - for example when the preload property is set. You can use the "notify" signal to be notified of available data.
Returned by:
Slot Access Functions:
Details:
The gtk:drop-target object is an event controller implementing a simple way to receive Drag-and-Drop operations. The most basic way to use a gtk:drop-target object to receive drops on a widget is to create it via the gtk:drop-target-new function passing in the GType of the data you want to receive and connect to the "current-drop" signal to receive the data.

The gtk:drop-target object supports more options, such as:
  • rejecting potential drops via the "accept" signal and the gtk:drop-target-reject function to let other drop targets handle the drop
  • tracking an ongoing drag operation before the drop via the "enter", "motion" and "leave" signals
  • configuring how to receive data by setting the preload property and listening for its availability via the value property
However, the gtk:drop-target object is ultimately modeled in a synchronous way and only supports data transferred via GType. If you want full control over an ongoing drop, the gtk:drop-target-async object gives you this ability.

While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the :drop-active state, which can be used to style the widget.
Signal Details:
The "accept" signal
lambda (target drop)    :run-last      
target
The gtk:drag-target object.
drop
The gdk:drop object.
Returns
True if drop is accepted.
The signal is emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, false will be returned and the drop target will ignore the drop. If true is returned, the drop is accepted for now but may be rejected later via a call to the gtk:drop-target-reject function or ultimately by returning false from the "drop" signal.

The default handler for this signal decides whether to accept the drop based on the formats provided by drop.

If the decision whether the drop will be accepted or rejected needs inspecting the data, this function should return true, the preload property should be set and the value should be inspected via the "notify::value" signal and then call the gtk:drop-target-reject function.
The "drop" signal
lambda (target value x y)    :run-last      
target
The gtk:drag-target object.
value
The g:value instance being dropped.
x
The double float with the x coordinate of the current pointer position.
y
The double float with the x coordinate of the current pointer position.
Returns
Whether the drop was accepted at the given pointer position.
The signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary. Otherwise, the handler returns true. In this case, this handler will accept the drop. The handler is responsible for reading the given value and performing the drop operation.
The "enter" signal
lambda (target x y)    :run-last      
target
The gtk:drag-target object.
x
A double float with the x coordinate of the current pointer position.
y
A double float with the x coordinate of the current pointer position.
Returns
A gdk:drag-action value with the preferred action for this drag operation or 0 if dropping is not supported at the current x,y location.
The signal is emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting.
The "leave" signal
lambda (target)    :run-last      
target
The gtk:drag-target object.
The signal is emitted on the drop site when the pointer leaves the widget. Its main purpose is to undo things done in the "enter" signal handler.
The "motion" signal
lambda (target x y)    :run-last      
target
The gtk:drag-target object.
x
The double float with the x coordinate of the current pointer position.
y
The double float with the x coordinate of the current pointer position.
Returns
The gdk:drag-action value with the preferred action for this drag operation or 0 if dropping is not supported at the current x,y location.
The signal is emitted while the pointer is moving over the drop target.
See also:
2023-9-18
Accessor gtk:drop-target-actions (object)
Syntax:
(gtk:drop-target-actions object) => actions
(setf (gtk:drop-target-actions object) actions)
Arguments:
object -- a gtk:drop-target object
actions -- a gdk:drag-action value
Details:
Accessor of the actions slot of the gtk:drop-target class. The gtk:drop-target-actions function gets the actions that this drop target supports. The (setf gtk:drop-target-actions) function sets the actions.
See also:
#2023-9-18
Accessor gtk:drop-target-current-drop (object)
Syntax:
(gtk:drop-target-current-drop object) => drop
Arguments:
object -- a gtk:drop-target object
drop -- a gdk:drop object with the current drop
Details:
Accessor of the current-drop slot of the gtk:drop-target class. The gtk:drop-target-current-drop function gets the currently handled drop operation. If no drop operation is going on, nil is returned.

Since 4.4
See also:
#2023-9-18
Accessor gtk:drop-target-drop (object)
Syntax:
(gtk:drop-target-drop object) => drop
Arguments:
object -- a gtk:drop-target object
drop -- a gdk:drop object with the current drop
Details:
Accessor of the drop slot of the gtk:drop-target class. The gtk:drop-target-drop function gets the currently handled drop operation.

Deprecated 4.4
See also:
#2023-9-18
Accessor gtk:drop-target-formats (object)
Syntax:
(gtk:drop-target-formats object) => formats
Arguments:
object -- a gtk:drop-target object
formats -- a gdk:content-formats instance with the supported data formats
Details:
Accessor of the formats slot of the gtk:drop-target class. The gtk:drop-target-formats function gets the data formats that this drop target accepts. If the result is nil, all formats are expected to be supported.
See also:
#2023-9-18
Accessor gtk:drop-target-preload (object)
Syntax:
(gtk:drop-target-preload object) => preload
(setf (gtk:drop-target-preload object) preload)
Arguments:
object -- a gtk:drop-target object
preload -- a boolean whether the drop data should be preloaded
Details:
Accessor of the preload slot of the gtk:drop-target class. The gtk:drop-target-preload function gets the value of the preload property. The (setf gtk:drop-target-preload) function sets the property.
See also:
#2023-9-18
Accessor gtk:drop-target-value (object)
Syntax:
(gtk:drop-target-value object) => value
Arguments:
object -- a gtk:drop-target object
value -- a g:value instance with the current drop data
Details:
Accessor of the value slot of the gtk:drop-target class. The gtk:drop-target-value function gets the value of the value property.
See also:
#2023-9-18
Function gtk:drop-target-new (gtype actions)
Arguments:
gtype -- a g:type-t type ID with the supported type
actions -- a gdk:drag-action value with the supported actions
Returns:
The new gtk:drop-target object.
Details:
Creates a new drop target. If the drop target should support more than one type, pass nil for gtype and then call the gtk:drop-target-gtypes function.
See also:
2024-11-2
Function gtk:drop-target-gtypes (target)
Syntax:
(gtk:drop-target-gtypes target) => gtypes
(setf (gtk:drop-target-gtypes target) gtypes)
Arguments:
target -- a gtk:drop-target object
gtypes -- a list of g:type-t type IDs
Details:
The gtk:drop-target-gtypes function gets the list of supported GTypes for target. If no type have been set, nil will be returned. The (setf gtk:drop-target) function sets the supported GTypes for the drop target.
See also:
2024-11-2
Function gtk:drop-target-reject (target)
Arguments:
target -- a gtk:drop-target object
Details:
Rejects the ongoing drop operation. If no drop operation is ongoing - when the "drop-current" signal returns nil - this function does nothing.

This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.
See also:
#2023-7-31

GtkDropTargetAsync

Class gtk:drop-target-async
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
actions
The actions property of type gdk:drag-action (Read / Write)
The actions that this drop target supports.
formats
The formats property of type gdk:content-formats (Read / Write)
The content formats that determines the supported data formats.
Returned by:
Slot Access Functions:
Details:
The gtk:drop-target-async object is an auxiliary object that can be used to receive Drag-and-Drop operations. It is the more complete but also more complex method of handling drop operations compared to GtkDropTarget and you should only use it if gtk:drop-target object does not provide all the features you need.

To use a gtk:drop-target-async object to receive drops on a widget, you create a gtk:drop-target-async object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with the gtk:widget-add-controller function.

During a drag operation, the first signal that a gtk:drop-target-async object emits is the "accept" signal, which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the "accept" signal accepts the drop if it finds a compatible data format and an action that is supported on both sides.

If it is, and the widget becomes a target, you will receive a "drag-enter" signal, followed by "drag-motion" signals as the pointer moves, optionally a "drop" signal when a drop happens, and finally a "drag-leave" signal when the pointer moves off the widget.

The "drag-enter" and "drag-motion" handler return a gdk:drag-action value to update the status of the ongoing operation. The "drop" signal handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling the gdk:drop-finish function.

Between the "drag-enter" and "drag-leave" signals the widget is a current drop target, and will receive the :drop-active state of the gtk:state-flags flags, which can be used by themes to style the widget as a drop target.
Signal Details:
The "accept" signal
lambda (target drop)    :run-last      
target
The gtk:drop-target-async object.
drop
The gdk:drop object.
Returns
True if the drop is accepted.
The signal is emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, false will be returned and the drop target will ignore the drop. If true is returned, the drop is accepted for now but may be rejected later via a call to the gtk:drop-target-async-reject-drop function or ultimately by returning false from the "drop" signal handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the drop object. If the decision whether the drop will be accepted or rejected needs further processing, such as inspecting the data, this function should return true and proceed as this drop was accepted and if it decides to reject the drop later, it should call the gtk:drop-target-async-reject-drop function.
The "drag-enter" signal
lambda (target drop x y)    :run-last      
target
The gtk:drop-target-async object.
drop
The gdk:drop object.
x
A double float with the x coordinate of the current pointer position.
y
A double float with the y coordinate of the current pointer position.
Returns
A boolean with the preferred action for this drag operation.
The signal is emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting.
The "drag-leave" signal
lambda (target drop)    :run-last      
The signal is emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in the "drag-enter" signal handler.
target
The gtk:drop-target-async object.
drop
The gdk:drop object.
The "drag-motion" signal
lambda (target drop x y)    :run-last      
The signal is emitted while the pointer is moving over the drop target.
target
The gtk:drop-target-async object.
drop
The gdk:drop object.
x
A double float with the x coordinate of the current pointer position.
y
A double float with the y coordinate of the current pointer position.
Returns
A boolean with the preferred action for this drag operation.
The "drop" signal
lambda (target drop x y)    :run-last      
The signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary. Otherwise, the handler returns true. In this case, this handler will accept the drop. The handler must ensure that the gdk:drop-finish function is called to let the source know that the drop is done. The call to the gdk:drop-finish function must only be done when all data has been received. To receive the data, use one of the read functions provides by the gdk:drop object such as the gdk:drop-read-async or gdk:drop-read-value-async functions.
target
The gtk:drop-target-async object.
drop
The gdk:drop object.
x
A double float with the x coordinate of the current pointer position.
y
A double float with the y coordinate of the current pointer position.
Returns
Whether the drop is accepted at the given pointer position.
See also:
2024-11-2
Accessor gtk:drop-target-async-actions (object)
Syntax:
(gtk:drop-target-async-actions object) => actions
(setf (gtk:drop-target-async-actions object) actions)
Arguments:
object -- a gtk:drop-target-async object
actions -- a gdk:drag-action value
Details:
Accessor of the actions slot of the gtk:drop-target-async class. The gtk:drop-target-async-actions function gets the actions that this drop target supports. The (setf gtk:drop-target-async-actions) function sets the actions.
See also:
#2023-9-29
Accessor gtk:drop-target-async-formats (object)
Syntax:
(gtk:drop-target-async-formats object) => formats
(setf (gtk:drop-target-async-formats object) formats)
Arguments:
object -- a gtk:drop-target-async object
formats -- a gdk:content-formats instance with the supported data formats
Details:
Accessor of the formats slot of the gtk:drop-target-async class. The gtk:drop-target-async-formats function gets the data formats that this drop target accepts. If the result is nil, all formats are expected to be supported. The (setf gtk:drop-target-async-formats) function sets the data formats that this drop target will accept.
See also:
#2023-9-29
Function gtk:drop-target-async-new (formats actions)
Arguments:
formats -- a gdk:content-formats instance with the supported data formats
actions -- a gdk:drag-action value with the supported actions
Returns:
The new gtk:drop-target-async object.
Details:
Creates a new gtk:drop-target-async object.
See also:
#2023-9-29
Function gtk:drop-target-async-reject-drop (target drop)
Arguments:
target -- a gtk:drop-target-async object
drop -- a gdk:drop object of an ongoing drag operation
Details:
Sets the drop as not accepted on this drag site. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.
See also:
#2023-9-29

GtkDropControllerMotion

Class gtk:drop-controller-motion
Superclasses:
gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
contains-pointer
The contains-pointer property of type :boolean (Read)
Whether the pointer of a Drag-and-Drop operation is in the controller’s widget or a descendant. See also the is-pointer property. When handling crossing events, this property is updated before the "enter" signal, but after the "leave" signal is emitted.
drop
The drop property of type gdk:drop (Read)
The ongoing drop operation over the widget of the controller or its descendant. If no drop operation is going on, this property returns nil. The event controller should not modify the drop, but it might want to query its properties. When handling crossing events, this property is updated before the "enter" signal, but after the "leave" signal is emitted.
is-pointer
The is-pointer property of type :boolean (Read)
Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also the contains-pointer property. When handling crossing events, this property is updated before the "enter" signal, but after the "leave" signal is emitted.
Returned by:
Slot Access Functions:
Details:
The gtk:drop-controller-motion object is an event controller meant for tracking the pointer hovering over a widget during a drag and drop operation. It is modeled after the gtk:event-controller-motion object so if you have used that, this should feel really familiar. The drop controller is not able to accept drops, use the gtk:drop-target object for that purpose.
Signal Details:
The "enter" signal
lambda (controller x y)    :run-last      
controller
The gtk:drop-controller-motion object.
x
The double float with the x coordinate of the pointer location.
y
The double float with the y coordinate of the pointer location.
Signals that the pointer has entered the widget.
The "leave" signal
lambda (controller)    :run-last      
controller
The gtk:drop-controller-motion object.
Signals that the pointer has left the widget.
The "motion" signal
lambda (controller x y)    :run-first      
controller
The gtk:drop-controller-motion object.
x
The double float with the x coordinate of the pointer location.
y
The double float with the y coordinate of the pointer location.
Emitted when the pointer moves inside the widget.
See also:
2024-11-2
Accessor gtk:drop-controller-motion-contains-pointer (object)
Syntax:
(gtk:drop-controller-motion-contains-pointer object) => contains
Arguments:
object -- a gtk:drop-controller-motion object
contains -- true if a dragging pointer is within object or one of its children
Details:
Accessor of the contains-pointer slot of the gtk:drop-controller-motion class. The gtk:drop-controller-motion-contains-pointer function returns the value of the property.
See also:
#2023-9-29
Accessor gtk:drop-controller-motion-drop (object)
Syntax:
(gtk:drop-controller-motion-drop object) => drop
Arguments:
object -- a gtk:drop-controller-motion object
drop -- a gdk:drop object currently happening within object or nil if none
Details:
Accessor of the drop slot of the gtk:drop-controller-motion class. The gtk:drop-controller-motion-drop function returns the value of the property.
See also:
#2023-9-29
Accessor gtk:drop-controller-motion-is-pointer (object)
Syntax:
(gtk:drop-controller-motion-is-pointer object) => is-pointer
Arguments:
object -- a gtk:drop-controller-motion object
is-pointer -- true if a dragging pointer is within object but not one of its children
Details:
Accessor of the is-pointer slot of the gtk:drop-controller-motion class. The gtk:drop-controller-motion-is-pointer function returns true if a Drag-and-Drop operation is within the widget object, not one of its children.
See also:
#2023-9-29
Function gtk:drop-controller-motion-new ()
Returns:
Details:
Creates a new event controller that will handle pointer motion events during drag and drop.
See also:
#2023-9-29

Miscellaneous

GtkAdjustment

Class gtk:adjustment
Superclasses:
gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
lower
The lower property of type :double (Read / Write)
The minimum value of the adjustment.
Default value: 0.0d0
page-increment
The page-increment property of type :double (Read / Write)
The page increment of the adjustment.
Default value: 0.0d0
page-size
The page-size property of type :double (Read / Write)
The page size of the adjustment. Note that the page size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value.
Default value: 0.0d0
step-increment
The step-increment property of type :double (Read / Write)
The step increment of the adjustment.
Default value: 0.0d0
upper
The upper property of type :double (Read / Write)
The maximum value of the adjustment. Note that values will be restricted by upper - page-size if the page-size property is nonzero.
Default value: 0.0d0
value
The value property of type :double (Read / Write)
The value of the adjustment.
Default value: 0.0d0
Returned by:
Slot Access Functions:
Details:
The gtk:adjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several widgets, including the gtk:spin-button, gtk:viewport, and gtk:range widget, which is a base class for the gtk:scale widget.

The gtk:adjustment object does not update the value itself. Instead it is left up to the owner of the gtk:adjustment object to control the value.
Signal Details:
The "changed" signal
lambda (adjustment)    :no-recurse      
adjustment
The gtk:adjustment object which received the signal.
Emitted when one or more of the adjustment properties have been changed, other than the value property.
The "value-changed" signal
lambda (adjustment)    :no-recurse      
adjustment
The gtk:adjustment object which received the signal.
Emitted when the value property of the adjustment has been changed.
See also:
2023-8-25
Accessor gtk:adjustment-lower (object)
Syntax:
(gtk:adjustment-lower object) => lower
(setf (gtk:adjustment-lower object) lower)
Arguments:
object -- a gtk:adjustment object
lower -- a double float with the minimum value
Details:
Accessor of the lower slot of the gtk:adjustment class. The gtk:adjustment-lower function retrieves the minimum value of the adjustment. The (setf gtk:adjustment-lower) function sets the minimum value of the adjustment.

When setting multiple adjustment properties via their individual setters, multiple "changed" signals will be emitted. However, since the emission of the "changed" signal is tied to the emission of the "notify" signals of the changed properties, it is possible to compress the "changed" signals into one by calling the g:object-freeze-notify and g:object-thaw-notify functions around the calls to the individual setters.

Alternatively, using the gtk:adjustment-configure function has the same effect of compressing "changed" emissions.
See also:
2023-8-25
Accessor gtk:adjustment-page-increment (object)
Syntax:
(gtk:adjustment-page-increment object) => increment
(setf (gtk:adjustment-page-increment object) increment)
Arguments:
object -- a gtk:adjustment object
increment -- a double float with the page increment
Details:
Accessor of the page-increment slot of the gtk:adjustment class. The gtk:adjustment-page-increment function retrieves the page increment of the adjustment. The (setf gtk:adjustment-page-increment) function sets the page increment of the adjustment.

See the gtk:adjustment-lower function about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.
See also:
2023-8-25
Accessor gtk:adjustment-page-size (object)
Syntax:
(gtk:adjustment-page-size object) => size
(setf (gtk:adjustment-page-size object) size)
Arguments:
object -- a gtk:adjustment object
size -- a double float with the page size
Details:
Accessor of the page-size slot of the gtk:adjustment class. The gtk:adjustment-page-size function retrieves the page size of the adjustment. The (setf gtk:adjustment-page-size) function sets the page size of the adjustment.

See the gtk:adjustment-lower function about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.
See also:
2023-8-25
Accessor gtk:adjustment-step-increment (object)
Syntax:
(gtk:adjustment-step-increment object) => increment
(setf (gtk:adjustment-step-increment object) increment)
Arguments:
object -- a gtk:adjustment object
increment -- a double float with the step increment
Details:
Accessor of the step-increment slot of the gtk:adjustment class. The gtk:adjustment-step-increment function retrieves the step increment of the adjustment. The (setf gtk:adjustment-step-increment) function sets the step increment of the adjustment.

See the gtk:adjustment-lower function about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.
See also:
2023-8-25
Accessor gtk:adjustment-upper (object)
Syntax:
(gtk:adjustment-upper object) => upper
(setf (gtk:adjustment-upper object) upper)
Arguments:
object -- a gtk:adjustment object
upper -- a double float with the maximum value
Details:
Accessor of the upper slot of the gtk:adjustment class. The gtk:adjustment-upper function retrieves the maximum value of the adjustment. The (setf gtk:adjustment-upper) function sets the maximum value of the adjustment.

Note that values will be restricted by the (upper - page-size) value if the page-size value is nonzero.

See the gtk:adjustment-lower function about how to compress multiple emissions of the "changed" signal when setting multiple adjustment properties.
See also:
2023-8-25
Accessor gtk:adjustment-value (object)
Syntax:
(gtk:adjustment-value object) => value
(setf (gtk:adjustment-value object) value)
Arguments:
object -- a gtk:adjustment object
value -- a double float with the value
Details:
Accessor of the value slot of the gtk:adjustment class. The gtk:adjustment-value function gets the current value of the adjustment. The (setf gtk:adjustment-value) function sets the adjustment value. The value is clamped to lie between the lower and upper values.

Note that for adjustments which are used in a gtk:scrollbar widget, the effective range of allowed values goes from the lower to (upper - page-size) values.
See also:
2023-8-25
Function gtk:adjustment-new (value lower upper step-increment page-increment page-size)
Arguments:
value -- a double float with the initial value
lower -- a double float with the minimum value
upper -- a double float with the maximum value
step-increment -- a double float with the step increment
page-increment -- a double float with the page increment
page-size -- a double float with the page size
Returns:
The new gtk:adjustment object.
Details:
Creates a new adjustment.
See also:
2023-8-25
Function gtk:adjustment-clamp-page (adjustment lower upper)
Arguments:
adjustment -- a gtk:adjustment object
lower -- a double float with the lower value
upper -- a double float with the upper value
Details:
Updates the adjustment value to ensure that the range between lower and upper is in the current page. If the range is larger than the page size, then only the start of it will be in the current page. A "changed" signal will be emitted if the value is changed.
See also:
2023-8-25
Function gtk:adjustment-configure (adjustment value lower upper step-increment page-increment page-size)
Arguments:
adjustment -- a gtk:adjustment object
value -- a double float with the new value
lower -- a double float with the new minimum value
upper -- a double float with the new maximum value
step-increment -- a double float with the new step increment
page-increment -- a double float with the new page increment
page-size -- a double float with the new page size
Details:
Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the "changed" signal. See the gtk:adjustment-lower function for an alternative way of compressing multiple emissions of "changed" signals into one.
See also:
#2023-8-25
Function gtk:adjustment-minimum-increment (adjustment)
Arguments:
adjustment -- a gtk:adjustment object
Returns:
The double float with the minimum increment of the adjustment.
Details:
Gets the smaller of step increment and page increment.
See also:
#2023-8-25

GtkSizeGroup

GEnum gtk:size-group-mode
Declaration:
(gobject:define-genum "GtkSizeGroupMode" size-group-mode
  (:export t
   :type-initializer "gtk_size_group_mode_get_type")
  (:none 0)
  (:horizontal 1)
  (:vertical 2)
  (:both 3))  
Values:
:none
Group has no effect.
:horizontal
Group affects horizontal requisition.
:vertical
Group affects vertical requisition.
:both
Group affects both horizontal and vertical requisition.
Details:
The mode of the size group determines the directions in which the gtk:size-group widget affects the requested sizes of its component widgets.
See also:
2025-2-23
Class gtk:size-group
Superclasses:
gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
mode
The mode property of type gtk:size-group-mode (Read / Write)
The directions in which the size group affects the requested sizes of its component widgets.
Default value: :horizontal
Returned by:
Slot Access Functions:
Details:
The gtk:size-group object provides a mechanism for grouping a number of widgets together so they all request the same amount of space. This is typically useful when you want a column of widgets to have the same size, but you cannot use a gtk:grid widget.

In detail, the size requested for each widget in a size group is the maximum of the sizes that would have been requested for each widget in the size group if they were not in the size group. The mode of the size group, see the gtk:size-group-mode function, determines whether this applies to the horizontal size, the vertical size, or both sizes.

Note that size groups only affect the amount of space requested, not the size that the widgets finally receive. If you want the widgets in a size group to actually be the same size, you need to pack them in such a way that they get the size they request and not more. In particular it does not make a lot of sense to set the expand flags on the widgets that are members of a size group.

Widgets can be part of multiple size groups. GTK will compute the horizontal size of a widget from the horizontal requisition of all widgets that can be reached from the widget by a chain of size groups of type :horizontal or :both, and the vertical size from the vertical requisition of all widgets that can be reached from the widget by a chain of size groups of type :vertical or :both.

Size groups and trading height-for-width
Warning: Generally, size groups do not interact well with widgets that trade height for width (or width for height), such as wrappable labels. Avoid using size groups with such widgets.

A size group with :horizontal or :vertival mode only consults non-contextual sizes of widgets other than the one being measured, since it has no knowledge of what size a widget will get allocated in the other orientation. This can lead to widgets in a size group actually requesting different contextual sizes, contrary to the purpose of the gtk:size-group widget.

In contrast, a size group with :both mode can properly propagate the available size in the opposite orientation when measuring widgets in the size group, which results in consistent and accurate measurements.

In case some mechanism other than a size group is already used to ensure that widgets in a size group all get the same size in one orientation, for example, some common ancestor is known to allocate the same width to all its children, and the size group is only really needed to also make the widgets request the same size in the other orientation, it is beneficial to still set the mode of the size group to the :both value. This lets the size group assume and count on sizes of the widgets in the former orientation being the same, which enables it to propagate the available size as described above.

Alternatives to size groups
Size groups have many limitations, such as only influencing size requests but not allocations, and poor height-for-width support. When possible, prefer using dedicated mechanisms that can properly ensure that the widgets get the same size.

Various container widgets and layout managers support a homogeneous layout mode, where they will explicitly give the same size to their children, see the homogeneous property. Using homogeneous mode can also have large performance benefits compared to either the same container in non-homogeneous mode, or to size groups.

The gtk:grid widget can be used to position widgets into rows and columns. Members of each column will have the same width among them. Likewise, members of each row will have the same height. On top of that, the heights can be made equal between all rows with the row-homogeneous property, and the widths can be made equal between all columns with the column-homogeneous property.
GtkSizeGroup as GtkBuildable:
Size groups can be specified in a UI definition by placing an <object> element with "GtkSizeGroup" class somewhere in the UI definition. The widgets that belong to the size group are specified by a <widgets> element that may contain multiple <widget> elements, one for each member of the size group. The name attribute gives the ID of the widget.
Examples:
A UI definition fragment with the gtk:size-group widget.
<object class="GtkSizeGroup">
  <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
  <widgets>
    <widget name="radio1"/>
    <widget name="radio2"/>
  </widgets>
</object>    
See also:
2025-2-23
Accessor gtk:size-group-mode (object)
Syntax:
(gtk:size-group-mode object) => mode
(setf (gtk:size-group-mode object) mode)
Arguments:
object -- a gtk:size-group object
mode -- a gtk:size-group-mode value to set for the size group
Details:
Accessor of the mode slot of the gtk:size-group class. The gtk:size-group-mode function gets the current mode of the size group. The (setf gtk:size-group-mode) function sets the mode.

The mode of the size group determines whether the widgets in the size group should all have the same horizontal requisition, :horizontal, all have the same vertical requisition, :vertical, or should all have the same requisition in both directions, :both.
See also:
2025-2-23
Function gtk:size-group-new (mode)
Arguments:
mode -- a gtk:size-group-mode value for the new size group
Returns:
The newly created gtk:size-group object.
Details:
Create a new size group.
See also:
2025-2-23
Function gtk:size-group-add-widget (group widget)
Arguments:
group -- a gtk:size-group object
widget -- a gtk:widget object to add
Details:
Adds a widget to a size group. In the future, the requisition of the widget will be determined as the maximum of its requisition and the requisition of the other widgets in the size group. Whether this applies horizontally, vertically, or in both directions depends on the mode of the size group. See the gtk:size-group-mode function.

When the widget is destroyed or no longer referenced elsewhere, it will be removed from the size group.
See also:
2025-2-23
Function gtk:size-group-remove-widget (group widget)
Arguments:
group -- a gtk:size-group object
widget -- a gtk:widget object to remove
Details:
Removes a widget from a size group.
See also:
2025-2-23
Function gtk:size-group-widgets (group)
Arguments:
group -- a gtk:size-group object
Returns:
The list of gtk:widget objects.
Details:
Returns the list of widgets associated with the size group.
See also:
2025-2-23

GtkFrame

Class gtk:frame
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget of the frame.
label
The label property of type :string (Read / Write)
The text of the label of the frame.
Default value: nil
label-widget
The label-widget property of type gtk:widget (Read / Write)
The widget to display in place of the usual frame label.
label-xalign
The label-xalign property of type :float (Read / Write)
The horizontal alignment of the label.
Allowed values: [0.0, 1.0]
Default value: 0.0
Returned by:
Slot Access Functions:
Details:
The gtk:frame widget is a widget that surrounds its child widget with a frame and an optional label.

Figure: GtkFrame

If present, the label is drawn inside the top edge of the frame. The horizontal position of the label can be controlled with the gtk:frame-label-xalign function.

The gtk:frame widget clips its child widget. You can use this to add rounded corners to widgets, but be aware that it also cuts off shadows. See the gtk:aspect-frame widget for a frame that constrains its child to a particular aspect ratio.
GtkFrame as GtkBuildable:
The gtk:frame implementation of the gtk:buildable interface supports placing a child in the label position by specifying label as the type attribute of a <child> element. A normal content child can be specified without specifying a <child> type attribute.

Example: A UI definition fragment with a gtk:frame widget
<object class="GtkFrame">
 <child type="label">
   <object class="GtkLabel" id="frame-label"/>
 </child>
 <child>
   <object class="GtkEntry" id="frame-content"/>
 </child>
</object>    
CSS nodes:
frame
├── <label widget>
╰── <child>    
The gtk:frame implementation has a main CSS node with name frame, which is used to draw the visible border. You can set the appearance of the border using CSS properties like border-style on this node.
See also:
2024-4-19
Accessor gtk:frame-child (object)
Syntax:
(gtk:frame-child object) => child
(setf (gtk:frame-child object) child)
Arguments:
object -- a gtk:frame widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:frame class. The gtk:frame-child function gets the child widget of the frame. The (setf gtk:frame-child) function sets the child widget.
See also:
2024-4-19
Accessor gtk:frame-label (object)
Syntax:
(gtk:frame-label object) => label
(setf (gtk:frame-label object) label)
Arguments:
object -- a gtk:frame widget
label -- a string with the text to use as the label of the frame
Details:
Accessor of the label slot of the gtk:frame class. The gtk:frame-label function returns the text in the label, or nil if there was no label widget or the label widget was not a gtk:label widget. The (setf gtk:frame-label) function sets the text of the label. If the label argument is nil, the current label is removed.

The frame will have a gtk:label widget for the label widget if a non-nil argument was passed to the gtk:frame-new function.
See also:
2024-4-19
Accessor gtk:frame-label-widget (object)
Syntax:
(gtk:frame-label-widget object) => widget
(setf (gtk:frame-label-widget object) widget)
Arguments:
object -- a gtk:frame widget
widget -- a gtk:widget label widget
Details:
Accessor of the label-widget slot of the gtk:frame class. The gtk:frame-label-widget function retrieves the label widget for the frame. The (setf gtk:frame-label-widget) function sets the label widget. This is the widget that will appear embedded in the top edge of the frame as a title.
See also:
2024-4-19
Accessor gtk:frame-label-xalign (object)
Syntax:
(gtk:frame-label-xalign object) => xalign
(setf (gtk:frame-label-xalign object) xalign)
Arguments:
object -- a gtk:frame widget
xalign -- a float with the position of the label along the top edge of the widget
Details:
Accessor of the label-xalign slot of the gtk:frame class. The gtk:frame-label-xalign function retrieves the x alignment of the label of the frame. The (setf gtk:frame-label-xalign) function sets the x alignment. The default value for a newly created frame is 0.0. A value of 0.0 represents left alignment, 1.0 represents right alignment. The change of the property is ignored if the value is not in the range of [0.0, 1.0].
See also:
2024-4-19
Function gtk:frame-new (&optional label)
Arguments:
label -- an optional string with the text to use as the label of the frame
Returns:
The new gtk:frame widget.
Details:
Creates a new frame widget, with an optional label. If the label argument is nil, the label is omitted.
See also:
2024-4-19
Function gtk:frame-label-align (frame)
Syntax:
(gtk:frame-label-align object) => align
(setf (gtk:frame-label-align object) align)
Arguments:
frame -- a gtk:frame widget
align -- a float with the position of the label along the top edge of the widget
Details:
The gtk:frame-label-align function retrieves the x alignment of the label of the frame. The (setf gtk:frame-label-align) function sets the x alignment. The default value for a newly created frame is 0.0. A value of 0.0 represents left alignment, 1.0 represents right alignment. The change of the property is ignored if the value is not in the range of [0.0, 1.0].
Notes:
This function is a variant of the gtk:frame-label-xalign function, which is the accessor function of the label-xalign property.
See also:
2024-4-19

GtkSeparator

Class gtk:separator
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:separator widget is a horizontal or vertical separator widget.

Figure: GtkSeparator

The gtk:separator widget can be used to group the widgets within a window. It displays a line with a shadow to make it appear sunken into the interface.
CSS nodes:
The gtk:separator implementation has a single CSS node with name separator. The node gets one of the .horizontal or .vertical style classes.
Accessibility:
The gtk:separator implementation uses the :separator role of the gtk:accessible-role enumeration.
See also:
2024-10-27
Function gtk:separator-new (orientation)
Arguments:
orientation -- a value of the gtk:orientation enumeration
Returns:
The new gtk:separator widget.
Details:
Creates a new separator widget with the given orientation.
See also:
2024-10-27

GtkSnapshot

Class gtk:snapshot
Superclasses:
gdk:snapshot, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:snapshot object is an auxiliary object that assists in creating gsk:render-node objects for widgets. It functions in a similar way to a Cairo context, and maintains a stack of render nodes and their associated transformations.

The node at the top of the stack is the the one that the snapshot functions operate on. Use the gtk:snapshot-push-... functions and gtk:snapshot-pop function to change the current node.

The typical way to obtain a gtk:snapshot object is as an argument to the gtk:widget-snapshot virtual function. If you need to create your own gtk:snapshot object, use the gtk:snapshot-new function.
See also:
2025-2-12
Function gtk:snapshot-new ()
Returns:
The newly allocated gtk:snapshot object.
Details:
Creates a new gtk:snapshot object.
See also:
2025-2-12
Function gtk:snapshot-to-node (snapshot)
Arguments:
snapshot -- a gtk:snapshot object
Returns:
The constructed gsk:render-node instance or nil if there are no nodes to render.
Details:
Returns the render node that was constructed by snapshot. Note that this function may return nil if nothing has been added to the snapshot or if its content does not produce pixels to be rendered.

After calling this function, it is no longer possible to add more nodes to snapshot.
See also:
2025-2-12
Function gtk:snapshot-to-paintable (snapshot &optional size)
Arguments:
snapshot -- a gtk:snapshot object
size -- a graphene:size-t instance for the size of the resulting paintable or the nil default value to use the bounds of the snapshot
Returns:
The new gdk:paintable object.
Details:
Returns a paintable encapsulating the render node that was constructed by snapshot. After calling this function, it is no longer possible to add more nodes to the snapshot.
See also:
2025-2-12
Function gtk:snapshot-push-opacity (snapshot opacity)
Arguments:
snapshot -- a gtk:snapshot object
opacity -- a number coerced to a double float for the opacity to use
Details:
Modifies the opacity of an image. The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-color-matrix (snapshot matrix offset)
Arguments:
snapshot -- a gtk:snapshot object
matrix -- a graphene:matrix-t instance for the color matrix to use
offset -- a graphene:vec4-t instance for the color offset to use
Details:
Modifies the colors of an image by applying an affine transformation in RGB space. In particular, the colors will be transformed by applying
pixel = transpose(matrix) * pixel + offset  
for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A.

The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-repeat (snapshot bounds &optional child-bounds)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the bounds within which to repeat
child-bounds -- a graphene:rect-t instance for the bounds of the child or nil to use the full size of the collected child node
Details:
Creates a node that repeats the child node. The child is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-clip (snapshot bounds)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the rectangle to clip to
Details:
Clips an image to a rectangle. The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-rounded-clip (snapshot bounds)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a gsk:rounded-rect instance for the rounded rectangle to clip to
Details:
Clips an image to a rounded rectangle. The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-cross-fade (snapshot progress)
Arguments:
snapshot -- a gtk:snapshot object
progress -- a number coerced to a double float for the progress between to 0.0 and 1.0
Details:
Snapshots a cross-fade operation between two images with the given progress. Until the first call to the gtk:snapshot-pop function, the start image will be snapshot. After that call, the end image will be recorded until the second call to the gtk:snapshot-pop function.

Calling this function requires two subsequent calls to the gtk:snapshot-pop function.
See also:
#2025-2-12
Function gtk:snapshot-push-blend (snapshot mode)
Arguments:
snapshot -- a gtk:snapshot object
mode -- a gsk:blend-mode value to use
Details:
Blends together two images with the given blend mode. Until the first call to the gtk:snapshot-pop function, the bottom image for the blend operation will be recorded. After that call, the top image to be blended will be recorded until the second call to the gtk:snapshot-pop function.

Calling this function requires two subsequent calls to the gtk:snapshot-pop function.
See also:
#2025-2-12
Function gtk:snapshot-push-blur (snapshot radius)
Arguments:
snapshot -- a gtk:snapshot object
radius -- a number coerced to a double float for the blur radius to use, must be postive
Details:
Blurs an image. The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
#2025-2-12
Function gtk:snapshot-push-shadow (snapshot shadows)
Arguments:
snapshot -- a gtk:snapshot object
shadows -- a list of the form '((color1 dx1 dy1 radius1) (color2 dx2 dy2 radius2) ...) with the shadows to apply
color -- a gdk:rgba instance for the color of the shadow
dx -- a number coerced to a single float for the horizontal offset of the shadow
dy -- a number coerced to a single float for the vertical offset of the shadow
radius -- a number coerced to a single float for the radius of the shadow
Details:
Applies a shadow to an image. The image is recorded until the next call to the gtk:snapshot-pop function.
See also:
2025-2-12
Function gtk:snapshot-push-mask (snapshot mode)
Arguments:
snapshot -- a gtk:snapshot object
mode -- a gsk:mask-mode value to use
Details:
Until the first call to the gtk:snapshot-pop function, the mask image for the mask operation will be recorded. After that call, the source image will be recorded until the second call to the gtk:snapshot-pop function.

Calling this function requires two subsequent calls to the gtk:snapshot-pop function.

Since 4.10
See also:
#2025-2-12
Function gtk:snapshot-push-fill (snapshot path rule)
Arguments:
snapshot -- a gtk:snapshot object
path -- a gsk:path instance for the path describing the area to fill
rule -- a gsk:fill-rule value to use
Details:
Fills the area given by path and rule with an image and discards everything outside of it. The image is recorded until the next call to the gtk:snapshot-pop function. If you want to fill the path with a color, the gtk:snapshot-append-fill function may be more convenient.

Since 4.14
See also:
2025-2-12
Function gtk:snapshot-push-stroke (snapshot path stroke)
Arguments:
snapshot -- a gtk:snapshot object
path -- a gsk:path instance for the path to stroke
stroke -- a gsk:stroke instance for the stroke attributes
Details:
Strokes the given path with the attributes given by stroke and an image. The image is recorded until the next call to the gtk:snapshot-pop function.

Note that the strokes are subject to the same transformation as everything else, so uneven scaling will cause horizontal and vertical strokes to have different widths.

If you want to stroke the path with a color, the gtk:snapshot-append-stroke function may be more convenient.

Since 4.14
See also:
2025-2-12
Function gtk:snapshot-pop (snapshot)
Arguments:
snapshot -- a gtk:snapshot object
Details:
Removes the top element from the stack of render nodes, and appends it to the node underneath it.
See also:
2025-2-12
Function gtk:snapshot-save (snapshot)
Arguments:
snapshot -- a gtk:snapshot object
Details:
Makes a copy of the current state of snapshot and saves it on an internal stack. When the gtk:snapshot-restore function is called, the snapshot will be restored to the saved state. Multiple calls to the gtk:snapshot-save function and the gtk:snapshot-restore function can be nested. Each call to the gtk:snapshot-restore function restores the state from the matching paired gtk:snapshot-save function.

It is necessary to clear all saved states with corresponding calls to the gtk:snapshot-restore function.
See also:
2025-2-12
Function gtk:snapshot-restore (snapshot)
Arguments:
snapshot -- a gtk:snapshot object
Details:
Restores snapshot to the state saved by a preceding call to the gtk:snapshot-save function and removes that state from the stack of saved states.
See also:
2025-2-12
Function gtk:snapshot-transform (snapshot transform)
Arguments:
snapshot -- a gtk:snapshot object
transform -- a gsk:transform instance
Details:
Transforms the coordinate system of the snapshot with the given transform.
See also:
#2025-2-12
Function gtk:snapshot-transform-matrix (snapshot matrix)
Arguments:
snapshot -- a gtk:snapshot object
matrix -- a graphene:matrix-t instance for the matrix to muliply the transform with
Details:
Transforms the coordinate system of the snapshot with the given matrix.
See also:
#2025-2-12
Function gtk:snapshot-translate (snapshot point)
Arguments:
snapshot -- a gtk:snapshot object
point -- a graphene:point-t instance for the point to translate snapshot by
Details:
Translates the coordinate system of the snapshot by point in 2-dimensional space.
See also:
2025-2-12
Function gtk:snapshot-translate-3d (snapshot point)
Arguments:
snapshot -- a gtk:snapshot object
point -- a graphene:point3d-t instance for the point to translate snapshot by
Details:
Translates the coordinate system of the snapshot by point.
See also:
#2025-2-12
Function gtk:snapshot-rotate (snapshot angle)
Arguments:
snapshot -- a gtk:snapshot object
angle -- a number coerced to a single float for the rotation angle, in degrees (clockwise)
Details:
Rotates the coordinate system of the snapshot by angle degrees in 2D space - or in 3D speak, rotates around the Z axis. The rotation happens around the origin point of (0,0) in the current coordinate system of the snapshot.

To rotate around axes other than the Z axis, use the gsk:transform-rotate-3d function.
See also:
2025-2-12
Function gtk:snapshot-rotate-3d (snapshot angle axis)
Arguments:
snapshot -- a gtk:snapshot object
angle -- a number coerced to a single float for the rotation angle, in degrees (clockwise)
axis -- a graphene:vec3-t instance for the rotation axis
Details:
Rotates the coordinate system of the snapshot by angle degrees around axis. For a rotation in 2D space, use the gtk:snapshot-rotate function.
See also:
#2025-2-12
Function gtk:snapshot-scale (snapshot xfactor yfactor)
Arguments:
snapshot -- a gtk:snapshot object
xfactor -- a number coerced to a single float for the scaling factor on the X axis
yfactor -- a number coerced to a single float for the scaling factor on the Y axis
Details:
Scales the coordinate system of the snapshot in 2-dimensional space by the given factors. Use the gtk:snapshot-scale-3d function to scale in all 3 dimensions.
See also:
2025-2-12
Function gtk:snapshot-scale-3d (snapshot xfactor yfactor zfactor)
Arguments:
snapshot -- a gtk:snapshot object
xfactor -- a number coerced to a single float for the scaling factor on the X axis
yfactor -- a number coerced to a single float for the scaling factor on the Y axis
zfactor -- a number coerced to a single float for the scaling factor on the Z axis
Details:
Scales the coordinate system of the snapshot by the given factors. Use the gtk:snapshot-scale function to scale in 2-dimensional space.
See also:
#2025-2-12
Function gtk:snapshot-perspective (snapshot depth)
Arguments:
snapshot -- a gtk:snapshot object
depth -- a number coerced to a single float for the distance of the Z=0 plane
Details:
Applies a perspective projection transform. See the gsk:transform-perspective function for a discussion on the details.
See also:
#2025-2-12
Function gtk:snapshot-append-node (snapshot node)
Arguments:
snapshot -- a gtk:snapshot object
node -- a gsk:render-node instance
Details:
Appends node to the current render node of snapshot, without changing the current node. If snapshot does not have a current node yet, node will become the initial node.
See also:
2025-2-12
Function gtk:snapshot-append-cairo (snapshot bounds)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the bounds of the new node
Returns:
The cairo:context-t instance suitable for drawing the contents of the newly created render node.
Details:
Creates a new gsk:cairo-node instance and appends it to the current render node of snapshot, without changing the current node.
See also:
2025-2-12
Function gtk:snapshot-append-color (snapshot color bounds)
Arguments:
snapshot -- a gtk:snapshot object
color -- a gdk:rgba instance for the color to draw
bounds -- a graphene:rect-t instance for the bounds of the node
Details:
Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot. You should try to avoid calling this function if color is transparent.
See also:
2025-2-12
Function gtk:snapshot-append-layout (snapshot layout color)
Arguments:
snapshot -- a gtk:snapshot object
layout -- a pango:layout instance to render
color -- a gdk:rgba instance for the foreground color to render the layout in
Details:
Creates render nodes for rendering layout in the given foregound color and appends them to the current node of snapshot without changing the current node. The current foreground color of the theme for a widget can be obtained with the gtk:widget-color function.

Note that if the layout does not produce any visible output, then nodes may not be added to the snapshot.
See also:
#2025-2-12
Function gtk:snapshot-append-border (snapshot outline widths colors)
Arguments:
snapshot -- a gtk:snapshot object
outline -- a gsk:rounded-rect instance for the outline of the border
widths -- a list of 4 numbers coerced to single floats for the stroke width of the border on the top, right, bottom, and left side respectivly
colors -- a list of 4 gdk:rgba instances for the colors used on the top, right, bottom, and left side
Details:
Appends a stroked border rectangle inside the given outline. The four sides of the border can have different widths and colors.
See also:
2025-2-12
Function gtk:snapshot-append-linear-gradient (snapshot bounds start end stops)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the rectangle to render the linear gradient into
start -- a graphene:point-t instance for the point at which the linear gradient will begin
end -- a graphene:point-t instance for the point at which the linear gradient will finish
stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
offset -- a number coerced to a single float for the offset of the color stop
color -- a gdk:rgba instance for the color at the given offset
Details:
Appends a linear gradient node with the given color stops to snapshot.
See also:
2025-2-12
Function gtk:snapshot-append-repeating-linear-gradient (snapshot bounds start end stops)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the rectangle to render the linear gradient into
start -- a graphene:point-t instance for the point at which the linear gradient will begin
end -- a graphene:point-t instance for the point at which the linear gradient will finish
stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
offset -- a number coerced to a single float for the offset of the color stop
color -- a gdk:rgba instance for the color at the given offset
Details:
Appends a repeating linear gradient node with the given stops to snapshot.
See also:
#2025-2-12
Function gtk:snapshot-append-radial-gradient (snapshot bounds center hradius vradius start end stops)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the rectangle to render the radial gradient into
center -- a graphene:point-t instance for the center of the radial gradient
hradius -- a number coerced to a single float for the horizontal radius
vradius -- a number coerced to a single float for the vertical radius
start -- a number coerced to a single float for the percentage >= 0 that defines the start of the radial gradient around center
end -- a number coerced to a single float for the percentage >= 0 that defines the end of the radial gradient around center
stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
offset -- a number coerced to a single float for the offset of the color stop
color -- a gdk:rgba instance for the color at the given offset
Details:
Appends a radial gradient node with the given stops to snapshot.
See also:
#2025-2-12
Function gtk:snapshot-append-repeating-radial-gradient (snapshot bounds center hradius vradius start end stops)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the rectangle to render the radial gradient into
center -- a graphene:point-t instance for the center of the radial gradient
hradius -- a number coerced to a single float for the horizontal radius
vradius -- a number coerced to a single float for the vertical radius
start -- a number coerced to a single float for the percentage >= 0 that defines the start of the radial gradient around center
end -- a number coerced to a single float for the percentage >= 0 that defines the end of the radial gradient around center
stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
offset -- a number coerced to a single float for the offset of the color stop
color -- a gdk:rgba instance for the color at the given offset
Details:
Appends a repeating radial gradient node with the given stops to snapshot.
See also:
#2025-2-12
Function gtk:snapshot-append-conic-gradient (snapshot bounds center rotation stops)
Arguments:
snapshot -- a gtk:snapshot object
bounds -- a graphene:rect-t instance for the bounds of the render node
center -- a graphene:point-t instance for the center of the gradient
rotation -- a number coerced to a single float for the rotation of the gradient, in degrees
stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
offset -- a number coerced to a single float for the offset of the color stop
color -- a gdk:rgba instance for the color at the given offset
Details:
Appends a conic gradient node with the given stops to snapshot.
See also:
#2025-2-12
Function gtk:snapshot-append-inset-shadow (snapshot outline color dx dy spread radius)
Arguments:
snapshot -- a gtk:snapshot object
outline -- a gsk:rounded-rect instance for the outline of the border
color -- a gdk:rgba instance for the color of the shadow
dx -- a number coerced to a single float for the horizontal offset of the shadow
dy -- a number coerced to a single float for the vertical offset of the shadow
spread -- a number coerced to a single float representing how far the shadow spreads towards the inside
radius -- a number coerced to a single float representing how much blur to apply to the shadow
Details:
Appends an inset shadow into the box given by outline.
See also:
#2025-2-12
Function gtk:snapshot-append-outset-shadow (snapshot outline color dx dy spread radius)
Arguments:
snapshot -- a gtk:snapshot object
outline -- a gsk:rounded-rect instance for the outline of the region surrounded by the shadow
color -- a gdk:rgba instance for the color of the shadow
dx -- a number coerced to a single float for the horizontal offset of shadow
dy -- a number coerced to a single float for the vertical offset of shadow
spread -- a number coerced to a single float representing how far the shadow spreads towards the outside
radius -- a number coerced to a single float representing how much blur to apply to the shadow
Details:
Appends an outset shadow node around the box given by outline.
See also:
#2025-2-12
Function gtk:snapshot-append-texture (snapshot texture bounds)
Arguments:
snapshot -- a gtk:snapshot object
texture -- a gdk:texture object for the texture to render
bounds -- a graphene:rect-t instance for the bounds of the new node
Details:
Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot. If the texture needs to be scaled to fill bounds, linear filtering is used. See the gtk:snapshot-append-scaled-texture function if you need other filtering, such as nearest-neighbour.
See also:
2025-2-12
Function gtk:snapshot-append-scaled-texture (snapshot texture filter bounds)
Arguments:
snapshot -- a gtk:snapshot object
texture -- a gdk:texture object for the texture to render
filter -- a gsk:scaling-filter value for the filter to use
bounds -- a graphene:rect-t instance for the bounds of the new node
Details:
Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot. In contrast to the gtk:snapshot-append-texture function, this function provides control over the filter that is used for scaling.

Since 4.10
See also:
#2025-2-12
Function gtk:snapshot-append-fill (snapshot path rule color)
Arguments:
snapshot -- a gtk:snapshot object
path -- a gsk:path instance for the path describing the area to fill
rule -- a gsk:fill-rule value to use
color -- a gdk:rgba instance for the color to fill the path with
Details:
A convenience method to fill a path with a color. See the gtk:snapshot-push-fill function if you need to fill a path with more complex content than a color.

Since 4.14
See also:
2025-2-12
Function gtk:snapshot-append-stroke (snapshot path stroke color)
Arguments:
snapshot -- a gtk:snapshot object
path -- a gsk:path instance for the path to stroke
stroke -- a gsk:stroke instance for the stroke attributes
color -- a gdk:rgba instance for the color to fill the path with
Details:
A convenience method to stroke a path with a color. See the gtk:snapshot-push-stroke function if you need to stroke a path with more complex content than a color.

Since 4.14
See also:
2025-3-1

GtkTooltip

Class gtk:tooltip
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:tooltip object is an object representing a widget tooltip. Basic tooltips can be realized simply by using the gtk:widget-tooltip-text or gtk:widget-tooltip-markup functions without any explicit tooltip object.

When you need a tooltip with a little more fancy contents, like adding an image, or you want the tooltip to have different contents per gtk:tree-view row or cell, you will have to do a little more work:
  • Set the has-tooltip property to true, this will make GTK monitor the widget for motion and related events which are needed to determine when and where to show a tooltip.
  • Connect to the "query-tooltip" signal. The signal will be emitted when a tooltip is supposed to be shown. One of the arguments passed to the signal handler is a gtk:tooltip object. This is the object that we are about to display as a tooltip, and can be manipulated in your callback function using functions like the gtk:tooltip-set-icon function. There are functions for setting the markup of the tooltip, setting an image from a stock icon, or even putting in a custom widget.
  • Return true from your "query-tooltip" signal handler. This causes the tooltip to be show. If you return false, it will not be shown.
See also:
2024-7-8
Function gtk:tooltip-set-markup (tooltip markup)
Arguments:
tooltip -- a gtk:tooltip object
markup -- a markup string, or nil
Details:
Sets the text of the tooltip to be markup. The string must be marked up with Pango markup. If the markup argument is nil, the label will be hidden.
See also:
#2024-7-8
Function gtk:tooltip-set-text (tooltip text)
Arguments:
tooltip -- a gtk:tooltip object
text -- a text string, or nil
Details:
Sets the text of the tooltip to be text. If the text argument is nil, the label will be hidden. See also the gtk:tooltip-set-markup function.
See also:
#2024-7-8
Function gtk:tooltip-set-icon (tooltip paintable)
Arguments:
tooltip -- a gtk:tooltip object
paintable -- a gdk:paintable object, or nil
Details:
Sets the icon of the tooltip, which is in front of the text, to be paintable. If the paintable argument is nil, the image will be hidden.
See also:
#2024-7-8
Function gtk:tooltip-set-icon-from-icon-name (tooltip name)
Arguments:
tooltip -- a gtk:tooltip object
name -- a string with the icon name, or nil
Details:
Sets the icon of the tooltip, which is in front of the text, to be the icon indicated by name. If the name argument is nil, the image will be hidden.
See also:
#2024-7-8
Function gtk:tooltip-set-icon-from-gicon (tooltip gicon)
Arguments:
tooltip -- a gtk:tooltip widget
gicon -- a g:icon representing the icon, or nil
Details:
Sets the icon of the tooltip, which is in front of the text, to be the icon indicated by gicon. If the gicon argument is nil, the image will be hidden.
See also:
#2024-7-8
Function gtk:tooltip-set-custom (tooltip widget)
Arguments:
tooltip -- a gtk:tooltip object
widget -- a gtk:widget custom widget, or nil to unset the old custom widget
Details:
Replaces the widget packed into the tooltip with widget. The widget argument does not get destroyed when tooltip goes away. By default a box with a gtk:image widget and gtk:label widget is embedded in the tooltip, which can be configured using the gtk:tooltip-set-markup and gtk:tooltip-set-icon functions.
See also:
#2024-7-8
Function gtk:tooltip-set-tip-area (tooltip rectangle)
Arguments:
tooltip -- a gtk:tooltip object
rectangle -- a gdk:rectangle instance
Details:
Sets the area of the widget, where the contents of the tooltip apply, to be rectangle, in widget coordinates. This is especially useful for properly setting tooltips on gtk:tree-view rows and cells, gtk:icon-view widgets, etc.

For setting tooltips on the gtk:tree-view widget, please refer to the gtk:tree-view-set-tooltip-row and gtk:tree-view-set-tooltip-cell convenience functions for this.
See also:
#2024-7-8

GtkWidgetPaintable

Class gtk:widget-paintable
Superclasses:
gdk:paintable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
widget
The widget property of type gtk:widget (Read / Write)
The observed widget or nil if none.
Details:
The gtk:widget-paintable object is an implementation of the the gdk:paintable interface that allows displaying the contents of a gtk:widget object.

The gtk:widget-paintable object will also take care of the widget not being in a state where it can be drawn, like when it is not shown, and just draw nothing or where it does not have a size, like when it is hidden, and report no size in that case.

Of course, the gtk:widget-paintable object allows you to monitor widgets for size changes by emitting the "invalidate-size" signal whenever the size of the widget changes as well as for visual changes by emitting the "invalidate-contents" signal whenever the widget changes.

You can of course use a gtk:widget-paintable object everywhere a gdk:paintable object is allowed, including using it on a gtk:picture widget, or one of its parents, that it was set on itself via the gtk:picture-paintable function. The paintable will take care of recursion when this happens. If you do this however, ensure the can-shrink property is set to true or you might end up with an infinitely growing widget.
See also:
2023-8-31
Function gtk:widget-paintable-new (widget)
Arguments:
widget -- a gtk:widget object or nil
Returns:
The new gtk:widget-paintable object.
Details:
Creates a new paintable widget observing the given widget.
See also:
2024-11-2

GtkWindowControls

Class gtk:window-controls
Superclasses:
Documented Subclasses:
None
Direct Slots:
decoration-layout
The decoration-layout property of type :string (Read / Write)
The decoration layout for window buttons. If this property is not set, the gtk-decoration-layout setting is used.
Default value: nil
empty
The empty property of type :boolean (Read)
Whether the widget has any window buttons.
Default value: true
side
The empty property of type gtk:pack-type (Read / Write)
Whether the widget shows start or end side of the decoration layout.
Default value: :start
Returned by:
Slot Access Functions:
Details:
The gtk:window-controls widget shows window frame controls, such as Minimize, Maximize and Close buttons, and the window icon.

Figure: GtkWindowControls

The gtk:window-controls widget only displays start or end side of the controls, see the side property, so it is intended to be always used in pair with another gtk:window-controls widget using the opposite side, for example:
<object class="GtkBox">
  <child>
    <object class="GtkWindowControls">
      <property name="side">start</property>
    </object>
  </child>
  ...
  <child>
    <object class="GtkWindowControls">
      <property name="side">end</property>
    </object>
  </child>
</object>  
CSS nodes:
windowcontrols
├── [image.icon]
├── [button.minimize]
├── [button.maximize]
╰── [button.close]    
The gtk:window-controls implementation has a CSS node called windowcontrols. It contains subnodes corresponding to each title button. Which of the title buttons exist and where they are placed exactly depends on the desktop environment and the decoration-layout property. When the empty property is true, it gets the .empty style class.
Accessibility:
The gtk:window-controls implementation uses the :group role.
See also:
2025-3-29
Accessor gtk:window-controls-decoration-layout (object)
Syntax:
(gtk:window-controls-decoration-layout object) => layout
(setf (gtk:window-controls-decoration-layout object) layout)
Arguments:
object -- a gtk:window-controls widget
layout -- a string for the decoration layout, or nil to unset the decoration layout
Details:
Accessor of the decoration-layout slot of the gtk:window-controls class. The gtk:window-controls-decoration-layout function gets the decoration layout. The (setf gtk:window-controls-decoration-layout) function sets the decoration layout for the title buttons, overriding the gtk-decoration-layout setting.

The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close and icon (the window icon).

For example, "icon:minimize,maximize,close" specifies a icon on the left, and Minimize, Maximize and Close buttons on the right.

If the side property is the :start value from the gtk:pack-type enumeration, object will display the part before the colon, otherwise after that.
See also:
2025-3-29
Accessor gtk:window-controls-empty (object)
Syntax:
(gtk:window-controls-empty object) => empty
Arguments:
object -- a gtk:window-controls widget
empty -- true if the widget has window buttons, otherwise false
Details:
Accessor of the empty slot of the gtk:window-controls class. The gtk:window-controls-empty function gets whether the widget has any window buttons.
See also:
2025-3-29
Accessor gtk:window-controls-side (object)
Syntax:
(gtk:window-controls-side object) => side
(setf (gtk:window-controls-side object) side)
Arguments:
object -- a gtk:window-controls widget
side -- a gtk:pack-type value
Details:
Accessor of the side slot of the gtk:window-controls class. The gtk:window-controls-side function gets the side. The (setf gtk:window-controls-side) function sets the side for object, determining which part of decoration layout it uses.
See also:
2025-3-29
Function gtk:window-controls-new (side)
Arguments:
side -- a gtk:pack-type value
Returns:
The new gtk:window-controls widget.
Details:
Creates a new gtk:window-controls widget.
See also:
2025-3-29

GtkWindowHandle

Class gtk:window-handle
Superclasses:
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write)
The child widget.
Details:
The gtk:window-handle widget is a titlebar area widget. When added into a window, it can be dragged to move the window, and handles right click, double click and middle click as expected of a titlebar.
CSS nodes:
The gtk:window-handle implementation has a single CSS node with the name windowhandle.
Accessibility:
Until GTK 4.10, the gtk:window-handle implementation uses the :group role of the gtk:accessible-role enumeration. Starting from GTK 4.12, the gtk:window-handle implementation uses the :generic role.
See also:
2023-8-31
Accessor gtk:window-handle-child (object)
Syntax:
(gtk:window-handle-child object) => child
(setf (gtk:window-handle-child object) child)
Arguments:
object -- a gtk:window widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:window-handle class. The gtk:window-handle-child function gets the child widget of the window handle. The (setf gtk:window-handle-child) function sets the child widget.
See also:
2023-7-23
Function gtk:window-handle-new ()
Returns:
The new gtk:window-handle widget.
Details:
Creates new gtk:window-handle widget.
See also:
2023-7-23

GTK Core Reference

Library initialization and main loop

Before using GTK, you need to initialize it using the gtk:init function. This connects to the windowing system, sets up the locale and performs other initialization tasks. The gtk:init function exits the application if errors occur. To avoid this, you can use the gtk:init-check function, which allows you to recover from a failed GTK initialization. For instance, you might start up your application in text mode instead.

Like most GUI toolkits, GTK uses an event-driven programming model. When the application is doing nothing, GTK sits in the "main loop" and waits for input. If the user performs some action - say, a mouse click - then the main loop "wakes up" and delivers an event to GTK. GTK forwards the event to one or more widgets.

When widgets receive an event, they frequently emit one or more "signals". Signals notify your program that something interesting happened by invoking functions you have connected to the signal with the g:signal-connect function. Functions connected to a signal are often called "callbacks".

When your callbacks are invoked, you would typically take some action - for example, when an Open button is clicked you might display a gtk:file-chooser-dialog widget. After a callback finishes, GTK will return to the main loop and await more user input.

It is important to note that if you use the gtk:application class, the application class will take care of initializing GTK for you, as well as spinning the main loop.

Functions for library initialization

Function gtk:init ()
Details:
Call this function before using any other GTK functions in your GUI applications. It will initialize everything needed to operate the toolkit.

If you are using the gtk:application class, you do not have to call the gtk:init or gtk:init-check functions. The "GApplication::startup" handler does it for you.

This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface you want to call the gtk:init-check function instead.

GTK calls signal(SIGPIPE, SIG_IGN) during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after the gtk:init call, but notice that other libraries, for example, libdbus or gvfs, might do similar things.
See also:
2024-11-5
Function gtk:init-check ()
Returns:
True if the windowing system has been successfully initialized, false otherwise.
Details:
This function does the same work as the gtk:init function with only a single change. It does not terminate the program if the windowing system cannot be initialized. Instead it returns false on failure.

This way the application can fall back to some other means of communication with the user - for example a curses or command line interface.
See also:
2024-11-5
Function gtk:is-initialized ()
Returns:
The boolean with the initialization status.
Details:
Use this function to check if GTK has been initialized with the gtk:init or gtk:init-check functions.
See also:
2024-11-5
Function gtk:disable-setlocale ()
Details:
Prevents the gtk:init and gtk:init-check functions from automatically calling setlocale(LC_ALL, ""). You would want to use this function if you wanted to set the locale for your program to something other than the locale of the user, or if you wanted to set different values for different locale categories.

Most programs should not need to call this function.
See also:
#2024-11-5
Function gtk:default-language ()
Returns:
The default language as a pango:language instance.
Details:
Returns the Pango language instance for the default language currently in effect. Note that this can change over the life of an application. The default language is derived from the current locale. It determines, for example, whether GTK uses the right-to-left or left-to-right text direction.

This function is equivalent to the pango:language-default function. See that function for details.
Examples:
(setq lang (gtk:default-language))
=> #<PANGO-LANGUAGE {C7B3C51}>
(pango:language-to-string lang)
=> "de-de"    
See also:
2024-11-5
Function gtk:locale-direction ()
Returns:
The gtk:text-direction value of the current locale.
Details:
Gets the direction of the current locale. This is the expected reading direction for text and UI. This function depends on the current locale being set with the setlocale() function and will default to setting the :ltr direction otherwise. The :none direction will never be returned.

GTK sets the default text direction according to the locale during the gtk:init function, and you should normally use the gtk:widget-direction or gtk:widget-default-direction functions to obtain the current direction.

This function is only needed rare cases when the locale is changed after GTK has already been initialized.
Examples:
You can use the gtk:locale-direction function to update the default text direction as follows:
(setf (gtk:widget-default-direction) (gtk:locale-direction))
=> :LTR    
See also:
2024-11-5

Version Information

GTK provides version information, primarily useful in configure checks for builds that have a configure script. Applications will not typically use the features described here.

Functions for version information

Function gtk:major-version ()
Returns:
The unsigned integer with the major version number of the GTK library.
Details:
Returns the major version number of the GTK library. This function is in the library, so it represents the GTK library your code is running against.
See also:
2025-2-28
Function gtk:minor-version ()
Returns:
The unsigned integer with the minor version number of the GTK library.
Details:
Returns the minor version number of the GTK library. This function is in the library, so it represents the GTK library your code is running against.
See also:
2025-2-28
Function gtk:micro-version ()
Returns:
The unsigned integer with the micro version number of the GTK library.
Details:
Returns the micro version number of the GTK library. This function is in the library, so it represents the GTK library your code is running against.
See also:
2025-2-28
Function gtk:check-version (major minor micro)
Arguments:
major -- an unsigned integer for the required major version
minor -- an unsigned integer for the required minor version
micro -- an unsigned integer for the required micro version
Returns:
The nil value if the GTK library is compatible with the given version, or a string describing the version mismatch.
Details:
Checks that the GTK library in use is compatible with the given version. Compatibility is defined by two things: first the version of the running library is newer than the major.minor.micro version. Second the running library must be binary compatible with the major.minor.micro version (same major version).
See also:
2025-2-28
Function gtk:cl-cffi-gtk-build-info (&optional out)
Arguments:
out -- an optional stream, the default is *standard-output*
Details:
Provides informations about the installation and the versions of the loaded libraries.
Examples:
(gtk:cl-cffi-gtk-build-info)
=>
cl-cffi-gtk version: 0.9.0
cl-cffi-gtk build date: 15:1 2/28/2025
GTK version: 4.16.3
GLIB version: 2.82.1
GDK-Pixbuf version: 2.42.12
Pango version: 1.54.0
Cairo version: 1.18.2
Machine type: X86-64
Machine version: NIL
Software type: Win32
Software version: 6.2.9200
Lisp implementation type: SBCL
Lisp implementation version: 2.0.0
NIL    
See also:
2025-2-28

GtkSettings

GEnum gtk:system-setting
Declaration:
(gobject:define-genum "GtkSystemSetting" system-setting
  (:export t
   :type-initializer "gtk_system_setting_get_type")
  :dpi
  :font-name
  :font-config
  :display
  :icon-theme)  
Values:
:dpi
The gtk-xft-dpi setting has changed.
:font-name
The gtk-font-name setting has changed.
:font-config
The font configuration has changed in a way that requires text to be redrawn. This can be any of the gtk-xft-antialias, gtk-xft-hinting, gtk-xft-hintstyle gtk-xft-rgba or gtk-fontconfig-timestamp settings.
:display
The display has changed.
:icon-theme
The icon theme has changed in a way that requires icons to be looked up again.
Details:
Values that can be passed to the GtkWidget::system_setting_changed virtual function. The values indicate which system setting has changed. Widgets may need to drop caches, or react otherwise. Most of the values correspond to gtk:settings properties.
See also:
2024-10-13
GEnum gtk:font-rendering
Declaration:
(gobject:define-genum "GtkFontRendering" font-rendering
  (:export t
   :type-initializer "gtk_font_rendering_get_type")
  (:automatic 0)
  (:manual 1))  
Values:
:automatic
Set up font rendering automatically, taking factors like screen resolution and scale into account.
:manual
Follow low-level font-related settings when configuring font rendering.
Details:
Values for the gtk-font-rendering setting that influence how GTK renders fonts.

Since 4.16
See also:
2024-10-13
Class gtk:settings
Superclasses:
gtk:style-provider, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
gtk-alternative-button-order
The gtk-alternative-button-order property of type :boolean (Read / Write)
Whether buttons in dialogs should use the alternative button order.
Default value: false
gtk-alternative-sort-arrows
The gtk-alternative-sort-arrows property of type :boolean (Read / Write)
Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted in ascending order. When set to true, this order will be inverted.
Default value: false
gtk-application-prefer-dark-theme
The gtk-application-prefer-dark-theme property of type :boolean (Read / Write)
Whether the application prefers to use a dark theme. If a GTK theme includes a dark variant, it will be used instead of the configured theme.
Default value: false
gtk-cursor-aspect-ratio
The gtk-cursor-aspect-ratio property of type :float (Read / Write)
The aspect ratio of the text caret.
Allowed values: [0.0, 1.0]
Default value: 0.04
gtk-cursor-blink
The gtk-cursor-blink property of type :boolean (Read / Write)
Whether the cursor should blink. Also see the gtk-cursor-blink-timeout setting, which allows more flexible control over cursor blinking.
Default value: true
gtk-cursor-blink-time
The gtk-cursor-blink-time property of type :int (Read / Write)
Length of the cursor blink cycle, in milliseconds.
Allowed values: >= 100
Default value: 1200
gtk-cursor-blink-timeout
The gtk-cursor-blink-timeout property of type :int (Read / Write)
Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. Setting this to zero has the same effect as setting the gtk-cursor-blink property to false.
Allowed values: >= 1
Default value: 10
gtk-cursor-theme-name
The gtk-cursor-theme-name property of type :string (Read / Write)
Name of the cursor theme to use, or nil to use the default theme.
gtk-cursor-theme-size
The gtk-cursor-theme-size property of type :int (Read / Write)
Size to use for cursors, or 0 to use the default size.
Allowed values: [0,128]
Default value: 0
gtk-decoration-layout
The gtk-decoration-layout property of type :string (Read / Write)
This setting determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed at the left or right. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu). For example, "menu:minimize,maximize,close" specifies a menu on the left, and Minimize, Maximize and Close buttons on the right. Note that buttons will only be shown when they are meaningful. For example, a menu button only appears when the desktop shell does not show the application menu, and a Close button only appears on a window that can be closed. Also note that the setting can be overridden with the decoration-layout property of the header bar.
Default value: "menu:minimize,maximize,close"
gtk-dialogs-use-header
The gtk-dialogs-use-header property of type :boolean (Read / Write)
Whether built-in GTK dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. This setting does not affect custom dialogs using the gtk:dialog widget directly, or message dialogs.
Default value: false
gtk-dnd-drag-threshold
The gtk-dnd-drag-threshold property of type :int (Read / Write)
Number of pixels the cursor can move before dragging.
Allowed values: >= 1
Default value: 8
gtk-double-click-distance
The gtk-double-click-distance property of type :int (Read / Write)
Maximum distance in pixels allowed between two clicks for them to be considered a double click.
Allowed values: >= 0
Default value: 5
gtk-double-click-time
The gtk-double-click-time property of type :int (Read / Write)
Maximum time allowed between two clicks for them to be considered a double click, in milliseconds.
Allowed values: >= 0
Default value: 250
gtk-enable-accels
The gtk-enable-accels property of type :boolean (Read / Write)
Whether menu items should have visible accelerators which can be activated.
Default value: true
gtk-enable-animations
The gtk-enable-animations property of type :boolean (Read / Write)
Whether to enable toolkit-wide animations.
Default value: true
gtk-enable-event-sounds
The gtk-enable-event-sounds property of type :boolean (Read / Write)
Whether to play any event sounds at all. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
Default value: true
gtk-enable-input-feedback-sounds
The gtk-enable-input-feedback-sounds property of type :boolean (Read / Write)
Whether to play event sounds as feedback to user input. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
Default value: true
gtk-enable-primary-paste
The gtk-enable-primary-paste property of type :boolean (Read / Write)
Whether a middle click on a mouse should paste the "PRIMARY" clipboard content at the cursor location.
Default value: true
gtk-entry-password-hint-timeout
The gtk-entry-password-hint-timeout property of type :uint (Read / Write)
How long to show the last input character in hidden entries. This value is in milliseconds. The value 0 disables showing the last char. The value 600 is a good value for enabling it.
Default value: 0
gtk-entry-select-on-focus
The gtk-entry-select-on-focus property of type :boolean (Read / Write)
Whether to select the contents of an entry when it is focused.
Default value: true
gtk-error-bell
The gtk-error-bell property of type :boolean (Read / Write)
When true, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using the gdk:surface-beep function, the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects.
Default value: true
gtk-font-name
The gtk-font-name property of type :string (Read / Write)
Name of default font to use.
gtk-font-rendering
The gtk-font-rendering property of type gtk:font-rendering (Read / Write)
How GTK font rendering is set up. When set to :manual, GTK respects the low-level font-related settings (gtk-hint-font-metrics, gtk-xft-antialias, gtk-xft-hinting, gtk-xft-hintstyle and gtk-xft-rgba) as much as practical. When set to :automatic, GTK will consider factors such as screen resolution and scale in deciding how to render fonts. Since 4.16
Default value: :automatic
gtk-fontconfig-timestamp
The gtk-fontconfig-timestamp property of type :uint (Read / Write)
Timestamp of the current fontconfig configuration.
Default value: 0
gtk-hint-font-metrics
The gtk-hint-font-metrics property of type :boolean (Read / Write)
Whether hinting should be applied to font metrics. Note that this also turns off subpixel positioning of glyphs, since it conflicts with metrics hinting. Since 4.6
gtk-icon-theme-name
The gtk-icon-theme-name property of type :string (Read / Write)
Name of the icon theme to use.
gtk-im-module
The gtk-im-module property of type :string (Read / Write)
Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. This also can be a colon-separated list of input methods, which GTK will try in turn until it finds one available on the system. See the gtk:im-context class and the gtk-show-input-method-menu setting.
Default value: nil
gtk-keynav-use-caret
The gtk-keynav-use-caret property of type :boolean (Read / Write)
Whether GTK should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader.
Default value: false
gtk-label-select-on-focus
The gtk-label-select-on-focus property of type :boolean (Read / Write)
Whether to select the contents of a selectable label when it is focused.
Default value: true
gtk-long-press-time
The gtk-long-press-time property of type :uint (Read / Write)
The time for a button or touch press to be considered a "long press".
Allowed values: <= G_MAXINT
Default value: 50
gtk-overlay-scrolling
The gtk-overlay-scrolling property of type :boolean (Read / Write)
Whether scrolled windows may use overlayed scrolling indicators. If this is set to false, scrolled windows will have permanent scrollbars.
Default value: true
gtk-primary-button-warps-slider
The gtk-primary-button-warps-slider property of type :boolean (Read / Write)
Whether a click in a gtk:range widget trough should scroll to the click position or scroll by a single page in the respective direction.
Default value: true
gtk-print-backends
The gtk-print-backends property of type :string (Read / Write)
A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK installation, and may include "file", "cups", "lpr" or "papi".
Default value: "file,cups"
gtk-print-preview-command
The gtk-print-preview-command property of type :string (Read / Write)
A command to run for displaying the print preview. The command should contain a f placeholder, which will get replaced by the path to the PDF file. The command may also contain a s placeholder, which will get replaced by the path to a file containing the print settings in the format produced by the gtk:print-settings-to-file function. The preview application is responsible for removing the PDF file and the print settings file when it is done.
Default value: "evince --unlink-tempfile --preview --print-settings %s %f"
gtk-recent-files-enabled
The gtk-recent-files-enabled property of type :boolean (Read / Write)
Whether GTK should keep track of items inside the recently used resources list. If set to false, the list will always be empty.
Default value: true
gtk-recent-files-max-age
The gtk-recent-files-max-age property of type :int (Read / Write)
The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. If set to 0, the list will always be empty; if set to -1, no item will be removed.
Allowed values: >= 30
Default value: 30
gtk-shell-shows-app-menu
The shell-shows-app-menu property of type :boolean (Read / Write)
Set to true if the desktop environment is displaying the application menu, false if the application should display it itself.
Default value: false
gtk-shell-shows-desktop
The gtk-shell-shows-desktop property of type :boolean (Read / Write)
Set to true if the desktop environment is displaying the desktop folder, false if not.
Default value: true
gtk-shell-shows-menubar
The gtk-shell-shows-menubar property of type :boolean (Read / Write)
Set to true if the desktop environment is displaying the menubar, false if the application should display it itself.
Default value: false
gtk-show-status-shapes
The gtk-show-status-shapes property of type :boolean (Read / Write)
If true, widgets like switches include shapes to indicate their on/off state. Since 4.14
Default value: false
gtk-sound-theme-name
The gtk-sound-theme-name property of type :string (Read / Write)
The XDG sound theme to use for event sounds. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
gtk-split-cursor
The gtk-split-cursor property of type :boolean (Read / Write)
Whether two cursors should be displayed for mixed left-to-right and right-to-left text.
Default value: true
gtk-theme-name
The gtk-theme-name property of type :string (Read / Write)
Name of the theme to load.
gtk-titlebar-double-click
The gtk-titlebar-double-click property of type :string (Read / Write)
This setting determines the action to take when a double click occures on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
Default value: "toggle-maximize"
gtk-titlebar-middle-click
The gtk-titlebar-middle-click property of type :string (Read / Write)
This setting determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
Default value: "none"
gtk-titlebar-right-click
The gtk-titlebar-right-click property of type :string (Read / Write)
This setting determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
Default value: "menu"
gtk-xft-antialias
The gtk-xft-antialias property of type :int (Read / Write)
Whether to antialias Xft fonts: 0 = no, 1 = yes, -1 = default.
Allowed values: [-1,1]
Default value: -1
gtk-xft-dpi
The gtk-xft-dpi property of type :int (Read / Write)
Resolution for Xft, in 1024 * dots/inch. -1 to use default value.
Allowed values: [-1,1048576]
Default value: -1
gtk-xft-hinting
The gtk-xft-hinting property of type :int (Read / Write)
Whether to hint Xft fonts: 0 = no, 1 = yes, -1 = default.
Allowed values: [-1,1]
Default value: -1
gtk-xft-hintstyle
The gtk-xft-hintstyle property of type :string (Read / Write)
What degree of hinting to use: hintnone, hintslight, hintmedium, or hintfull.
Default value: nil
gtk-xft-rgba
The gtk-xft-rgba property of type :string (Read / Write)
Type of subpixel antialiasing: none, rgb, bgr, vrgb, vbgr.
Default value: nil
Slot Access Functions:
Details:
The gtk:settings object provide a mechanism to share global settings between applications.

On the X window system, this sharing is realized by an XSettings manager that is usually part of the desktop environment, along with utilities that let the user change these settings. On Wayland, the settings are obtained either via a settings portal, or by reading desktop settings from DConf.

In the absence of these sharing mechanisms, GTK reads default values for settings from settings.ini files in /etc/gtk-4.0, $XDG_CONFIG_DIRS/gtk-4.0 and $XDG_CONFIG_HOME/gtk-4.0. These files must be valid key files, see the g:key-file API, and have a section called "Settings". Themes can also provide default values for settings by installing a settings.ini file next to their gtk.css file.

Applications can override system-wide settings with the accessor functions of the slots. This should be restricted to special cases though. The gtk:settings settings are not meant as an application configuration facility.

There is one gtk:settings instance per display. It can be obtained with the gtk:settings-for-display function, but in many cases, it is more convenient to use the gtk:widget-settings function.
See also:
2024-5-25
Accessor gtk:settings-gtk-alternative-button-order (object)
Syntax:
(gtk:settings-gtk:alternative-button-order object) => setting
(setf (gtk:settings-gtk-alternative-button-order object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether buttons in dialogs should use the alternative button order
Details:
Accessor of the gtk-alternative-button-order slot of the gtk:settings class. Whether buttons in dialogs should use the alternative button order.
See also:
2023-8-30
Accessor gtk:settings-gtk-alternative-sort-arrows (object)
Syntax:
(gtk:settings-gtk-alternative-sort-arrows object) => setting
(setf (gtk:settings-gtk-alternative-sort-arrows object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean which controls the direction of sort indicators
Details:
Accessor of the gtk-alternative-sort-arrows slot of the gtk:settings class. Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted in ascending order. When set to true, this order will be inverted.
See also:
2023-8-30
Accessor gtk:settings-gtk-application-prefer-dark-theme (object)
Syntax:
(gtk:settings-gtk-application-prefer-dark-theme object) => setting
(setf (gtk:settings-gtk-application-prefer-dark-theme object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether the application prefers to use a dark theme
Details:
Accessor of the gtk-application-prefer-dark-theme slot of the gtk:settings class. Whether the application prefers to use a dark theme. If a GTK theme includes a dark variant, it will be used instead of the configured theme.
See also:
2023-8-30
Accessor gtk:settings-gtk-cursor-aspect-ratio (object)
Syntax:
(gtk:settings-gtk-cursor-aspect-ratio object) => setting
(setf (gtk:settings-gtk-cursor-aspect-ratio object) setting)
Arguments:
object -- a gtk:settings object
setting -- a float with the aspect ratio of the text caret
Details:
Accessor of the gtk-cursor-aspect-ratio slot of the gtk:settings class. The aspect ratio of the text caret.
See also:
2023-8-30
Syntax:
(gtk:settings-gtk-cursor-blink object) => setting
(setf (gtk:settings-gtk-cursor-blink object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether the cursor should blink
Details:
Accessor of the gtk-cursor-blink slot of the gtk:settings class. Whether the cursor should blink. Also see the gtk-cursor-blink-timeout setting, which allows more flexible control over cursor blinking.
See also:
2023-8-30
Syntax:
(gtk:settings-gtk-cursor-blink-time object) => setting
(setf (gtk:settings-gtk-cursor-blink-time object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the length of the cursor blink cycle, in milliseconds
Details:
Accessor of the gtk-cursor-blink-time slot of the gtk:settings class. Length of the cursor blink cycle, in milliseconds.
See also:
2023-8-30
Syntax:
(gtk:settings-gtk-cursor-blink-timeout object) => setting
(setf (gtk:settings-gtk-cursor-blink-timeout object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the time after which the cursor stops blinking, in seconds
Details:
Accessor of the gtk-cursor-blink-timeout slot of the gtk:settings class. Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. Setting this to zero has the same effect as setting the gtk-cursor-blink property to false.
See also:
2023-8-30
Accessor gtk:settings-gtk-cursor-theme-name (object)
Syntax:
(gtk:settings-gtk-cursor-theme-name object) => setting
(setf (gtk:settings-gtk-cursor-theme-name object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the cursor theme name
Details:
Accessor of the gtk-cursor-theme-name slot of the gtk:settings class. Name of the cursor theme to use, or nil to use the default theme.
See also:
2023-8-30
Accessor gtk:settings-gtk-cursor-theme-size (object)
Syntax:
(gtk:settings-gtk-cursor-theme-size object) => setting
(setf (gtk:settings-gtk-cursor-theme-size object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the size to use for cursors
Details:
Accessor of the gtk-cursor-theme-size slot of the gtk:settings class. Size to use for cursors, or 0 to use the default size.
See also:
2023-8-30
Accessor gtk:settings-gtk-decoration-layout (object)
Syntax:
(gtk:settings-gtk-decoration-layout object) => setting
(setf (gtk:settings-gtk-decoration-layout object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the settings for buttons
Details:
Accessor of the gtk-decoration-layout slot of the gtk:settings class. This setting determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed at the left of right.

The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu).

For example, "menu:minimize,maximize,close" specifies a menu on the left, and Minimize, Maximize and Close buttons on the right.

Note that buttons will only be shown when they are meaningful. For example, a menu button only appears when the desktop shell does not show the app menu, and a Close button only appears on a window that can be closed.

Also note that the setting can be overridden with the decoration-layout property of the header bar.
See also:
2023-8-30
Accessor gtk:settings-gtk-dialogs-use-header (object)
Syntax:
(gtk:settings-gtk-dialogs-use-header object) => setting
(setf (gtk:settings-gtk-dialogs-use-header object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether dialogs use a header bar
Details:
Accessor of the gtk-dialogs-use-header slot of the gtk:settings class. Whether built-in GTK dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. This setting does not affect custom dialogs using the gtk:dialog widget directly, or message dialogs.
See also:
2023-8-30
Accessor gtk:settings-gtk-dnd-drag-threshold (object)
Syntax:
(gtk:settings-gtk-dnd-drag-threshold object) => setting
(setf (gtk:settings-gtk-dnd-drag-threshold object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the number of pixels the cursor can move
Details:
Accessor of the gtk-dnd-drag-threshold slot of the gtk:settings class. Number of pixels the cursor can move before dragging.
See also:
2023-8-30
Accessor gtk:settings-gtk-double-click-distance (object)
Syntax:
(gtk:settings-gtk-double-click-distance object) => setting
(setf (gtk:settings-gtk-double-click-distance object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the maximum distance in pixels
Details:
Accessor of the gtk-double-click-distance slot of the gtk:settings class. Maximum distance in pixels allowed between two clicks for them to be considered a double click.
See also:
2023-8-30
Accessor gtk:settings-gtk-double-click-time (object)
Syntax:
(gtk:settings-gtk-double-click-time object) => setting
(setf (gtk:settings-gtk-double-click-time object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the maximum time allowed between two clicks
Details:
Accessor of the gtk-double-click-time slot of the gtk:settings class. Maximum time allowed between two clicks for them to be considered a double click, in milliseconds.
See also:
2023-8-30
Accessor gtk:settings-gtk-enable-accels (object)
Syntax:
(gtk:settings-gtk-enable-accels object) => setting
(setf (gtk:settings-gtk-enable-accels object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether menu items should have visible accelerators
Details:
Accessor of the gtk-enable-accels slot of the gtk:settings class. Whether menu items should have visible accelerators which can be activated.
See also:
2023-8-30
Accessor gtk:settings-gtk-enable-animations (object)
Syntax:
(gtk:settings-gtk-enable-animations object) => setting
(setf (gtk:settings-gtk-enable-animations object) setting)
Arguments:
object -- the gtk:settings object
setting -- a boolean whether to enable animations
Details:
Accessor of the gtk-enable-animations slot of the gtk:settings class. Whether to enable toolkit-wide animations. The default value is true.
See also:
2023-8-30
Accessor gtk:settings-gtk-enable-event-sounds (object)
Syntax:
(gtk:settings-gtk-enable-event-sounds object) => setting
(setf (gtk:settings-gtk-enable-event-sounds object) setting)
Arguments:
object -- the gtk:settings object
setting -- a boolean whether to play any event sounds at all
Details:
Accessor of the gtk-enable-event-sounds slot of the gtk:settings class. Whether to play any event sounds at all. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
See also:
2023-8-30
Accessor gtk:settings-gtk-enable-input-feedback-sounds (object)
Syntax:
(gtk:settings-gtk-enable-input-feedback-sounds object) => setting
(setf (gtk:settings-gtk-enable-input-feedback-sounds object) setting)
Arguments:
object -- the gtk:settings object
setting -- a boolean whether to play any event sounds at all
Details:
Accessor of the gtk-enable-input-feedback-sounds slot of the gtk:settings class. Whether to play event sounds as feedback to user input. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
See also:
2023-8-30
Accessor gtk:settings-gtk-enable-primary-paste (object)
Syntax:
(gtk:settings-gtk-enable-primary-paste object) => setting
(setf (gtk:settings-gtk-enable-primary-paste object) setting)
Arguments:
object -- the gtk:settings object
setting -- a boolean whether a middle click should paste the "PRIMARY" clipboard
Details:
Accessor of the gtk-enable-primary-paste slot of the gtk:settings class. Whether a middle click on a mouse should paste the "PRIMARY" clipboard content at the cursor location.
See also:
2023-8-30
Accessor gtk:settings-gtk-entry-password-hint-timeout (object)
Syntax:
(gtk:settings-gtk-entry-password-hint-timeout object) => setting
(setf (gtk:settings-gtk-entry-password-hint-timeout object) setting)
Arguments:
object -- the gtk:settings object
setting -- an unsigned integer for how long to show the last input
Details:
Accessor of the gtk-entry-password-hint-timeout slot of the gtk:settings class. How long to show the last input character in hidden entries. This value is in milliseconds. The value 0 disables showing the last char. The value 600 is a good value for enabling it.
See also:
2023-8-30
Accessor gtk:settings-gtk-entry-select-on-focus (object)
Syntax:
(gtk:settings-gtk-entry-select-on-focus object) => setting
(setf (gtk:settings-gtk-entry-select-on-focus object) setting)
Arguments:
object -- the gtk:settings object
setting -- a boolean whether to select the contents of an entry
Details:
Accessor of the gtk-entry-select-on-focus slot of the gtk:settings class. Whether to select the contents of an entry when it is focused.
See also:
2023-8-30
Accessor gtk:settings-gtk-error-bell (object)
Syntax:
(gtk:settings-gtk-error-bell object) => setting
(setf (gtk:settings-gtk-error-bell object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether errors well cause a beep
Details:
Accessor of the gtk-error-bell slot of the gtk:settings class. When true, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using the gdk:surface-beep function, the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects.
See also:
2023-10-2
Accessor gtk:settings-gtk-font-name (object)
Syntax:
(gtk:settings-gtk-font-name object) => setting
(setf (gtk:settings-gtk-font-name object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the name of the default font to use
Details:
Accessor of the gtk-font-name slot of the gtk:settings class. Name of the default font to use.
See also:
2023-8-30
Accessor gtk:settings-gtk-fontconfig-timestamp (object)
Syntax:
(gtk:settings-gtk-fontconfig-timestamp object) => setting
(setf (gtk:settings-gtk-fontconfig-timestamp object) setting)
Arguments:
object -- a gtk:settings object
setting -- an unsigned integer with the timestamp
Details:
Accessor of the gtk-fontconfig-timestamp slot of the gtk:settings class. Timestamp of the current fontconfig configuration.
See also:
2023-8-30
Accessor gtk:settings-gtk-hint-font-metrics (object)
Syntax:
(gtk:settings-gtk-hint-font-metrics object) => setting
(setf (gtk:settings-gtk-hint-font-metrics object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether hinting should be applied to font metrics
Details:
Accessor of the gtk-hint-font-metrics slot of the gtk:settings class. Whether hinting should be applied to font metrics. Note that this also turns off subpixel positioning of glyphs, since it conflicts with metrics hinting.

Since 4.6
See also:
2023-8-30
Accessor gtk:settings-gtk-icon-theme-name (object)
Syntax:
(gtk:settings-gtk-icon-theme-name object) => setting
(setf (gtk:settings-gtk-icon-theme-name object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the icon theme name
Details:
Accessor of the gtk-icon-theme-name slot of the gtk:settings class. Name of the icon theme to use.
See also:
2023-8-30
Accessor gtk:settings-gtk-im-module (object)
Syntax:
(gtk:settings-gtk-im-module object) => setting
(setf (gtk:settings-gtk-im-module object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the IM module
Details:
Accessor of the gtk-im-module slot of the gtk:settings class. Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. This also can be a colon-separated list of input methods, which GTK will try in turn until it finds one available on the system. See the gtk:im-context class and the gtk-show-input-method-menu setting.
See also:
gtk:settings
gtk:im-context
gtk:settings-gtk-show-input-method-menu
2023-8-30
Accessor gtk:settings-gtk-keynav-use-caret (object)
Syntax:
(gtk:settings-gtk-keynav-use-caret object) => setting
(setf (gtk:settings-gtk-keynav-use-caret object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether GTK should make sure that text can be navigated with a caret
Details:
Accessor of the gtk-keynav-use-caret slot of the gtk:settings class. Whether GTK should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader.
See also:
2023-8-30
Accessor gtk:settings-gtk-label-select-on-focus (object)
Syntax:
(gtk:settings-gtk-label-select-on-focus object) => setting
(setf (gtk:settings-gtk-label-select-on-focus object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether to select the contents of a selectable label
Details:
Accessor of the gtk-label-select-on-focus slot of the gtk:settings class. Whether to select the contents of a selectable label when it is focused.
See also:
2023-8-30
Accessor gtk:settings-gtk-long-press-time (object)
Syntax:
(gtk:settings-gtk-long-press-time object) => setting
(setf (gtk:settings-gtk-long-press-time object) setting)
Arguments:
object -- a gtk:settings object
setting -- an unsigned integer with the time for a button or touch press to be considered a "long press"
Details:
Accessor of the gtk-long-press-time slot of the gtk:settings class. The time for a button or touch press to be considered a "long press".
See also:
2023-8-30
Accessor gtk:settings-gtk-overlay-scrolling (object)
Syntax:
(gtk:settings-gtk-overlay-scrolling object) => setting
(setf (gtk:settings-gtk-overlay-scrolling object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether scrolled windows may use overlayed scrolled indicators
Details:
Accessor of the gtk-overlay-scrolling slot of the gtk:settings class. Whether scrolled windows may use overlayed scrolling indicators. If this is set to false, scrolled windows will have permanent scrollbars.
See also:
2023-8-30
Accessor gtk:settings-gtk-primary-button-warps-slider (object)
Syntax:
(gtk:settings-gtk-primary-button-warps-slider object) => setting
(setf (gtk:settings-gtk-primary-button-warps-slider object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether a click should scroll to the click position
Details:
Accessor of the gtk-primary-buton-warps-slider slot of the gtk:settings class. Whether a click in a gtk:range widget trough should scroll to the click position or scroll by a single page in the respective direction.
See also:
2023-8-30
Accessor gtk:settings-gtk-print-backends (object)
Syntax:
(gtk:settings-gtk-print-backends object) => setting
(setf (gtk:settings-gtk-print-backends object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with a list of print backends
Details:
Accessor of the gtk-print-backends slot of the gtk:settings class. A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK installation, and may include "file", "cups", "lpr" or "papi".
See also:
2023-8-30
Accessor gtk:settings-gtk-print-preview-command (object)
Syntax:
(gtk:settings-gtk-print-preview-command object) => setting
(setf (gtk:settings-gtk-print-preview-command object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with a command to run for displaying the print preview
Details:
Accessor of the gtk-print-preview-command slot of the gtk:settings class. A command to run for displaying the print preview. The command should contain a f placeholder, which will get replaced by the path to the PDF file. The command may also contain a s placeholder, which will get replaced by the path to a file containing the print settings in the format produced by the gtk:print-settings-to-file function. The preview application is responsible for removing the PDF file and the print settings file when it is done.
See also:
2023-8-30
Accessor gtk:settings-gtk-recent-files-enabled (object)
Syntax:
(gtk:settings-gtk-recent-files-enabled object) => setting
(setf (gtk:settings-gtk-recent-files-enabled object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether GTK should keep track of items inside the recently used resources list
Details:
Accessor of the gtk-recent-files-enabled slot of the gtk:settings class. Whether GTK should keep track of items inside the recently used resources list. If set to false, the list will always be empty.
See also:
2023-8-30
Accessor gtk:settings-gtk-recent-files-max-age (object)
Syntax:
(gtk:settings-gtk-recent-files-max-age object) => setting
(setf (gtk:settings-gtk-recent-files-max-age object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the maximum age, in days
Details:
Accessor of the gtk-recent-files-max-page slot of the gtk:settings class. The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. If set to 0, the list will always be empty, if set to -1, no item will be removed.
See also:
2023-8-30
Accessor gtk:settings-gtk-shell-shows-app-menu (object)
Syntax:
(gtk:settings-gtk-shell-shows-app-menu object) => setting
(setf (gtk:settings-gtk-shell-shows-app-menu object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether the environment is displaying the application menu
Details:
Accessor of the gtk-shell-shows-app-menu slot of the gtk:settings class. Set to true if the desktop environment is displaying the application menu, false if the application should display it itself.
See also:
2023-8-30
Accessor gtk:settings-gtk-shell-shows-desktop (object)
Syntax:
(gtk:settings-gtk-shell-shows-desktop object) => setting
(setf (gtk:settings-gtk-shell-shows-desktop object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether the environment is displaying the desktop folder
Details:
Accessor of the gtk-shell-shows-desktop slot of the gtk:settings class. Set to true if the desktop environment is displaying the desktop folder, false if not.
See also:
2023-8-30
Accessor gtk:settings-gtk-shell-shows-menubar (object)
Syntax:
(gtk:settings-gtk-shell-shows-menubar object) => setting
(setf (gtk:settings-gtk-shell-shows-menubar object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether the environment is displaying the menubar
Details:
Accessor of the gtk-shell-shows-menubar slot of the gtk:settings class. Set to true if the desktop environment is displaying the menubar, false if the application should display it itself.
See also:
2023-8-30
Accessor gtk:settings-gtk-show-status-shapes (object)
Syntax:
(gtk:settings-gtk-shell-shows-menubar object) => setting
(setf (gtk:settings-gtk-shell-shows-menubar object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether widgets include shapes to indicate their on/off state
Details:
Accessor of the gtk-shell-shows-menubar slot of the gtk:settings class. If true, widgets like switches include shapes to indicate their on/off state.

Since 4.14
See also:
2024-5-26
Accessor gtk:settings-gtk-sound-theme-name (object)
Syntax:
(gtk:settings-gtk-sound-theme-name object) => setting
(setf (gtk:settings-gtk-sound-theme-name object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the sound theme name
Details:
Accessor of the gtk-sound-theme-name slot of the gtk:settings class. The XDG sound theme to use for event sounds. See the Sound Theme specification for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with the libcanberra library.
See also:
2023-8-30
Accessor gtk:settings-gtk-split-cursor (object)
Syntax:
(gtk:settings-gtk-split-cursor object) => setting
(setf (gtk:settings-gtk-split-cursor object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether two cursors should be displayed for mixed left-to-right and right-to-left text
Details:
Accessor of the gtk-split-cursor slot of the gtk:settings class. Whether two cursors should be displayed for mixed left-to-right and right-to-left text.
See also:
2023-8-30
Accessor gtk:settings-gtk-theme-name (object)
Syntax:
(gtk:settings-gtk-theme-name object) => setting
(setf (gtk:settings-gtk-theme-name object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the theme name
Details:
Accessor of the gtk-theme-name slot of the gtk:settings class. Name of the theme to load.
See also:
2023-8-30
Accessor gtk:settings-gtk-titlebar-double-click (object)
Syntax:
(gtk:settings-gtk-titlebar-double-click object) => setting
(setf (gtk:settings-gtk-titlebar-double-click object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with an action
Details:
Accessor of the gtk-titlebar-double-click slot of the gtk:settings class. This setting determines the action to take when a double click occures on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
See also:
2023-8-30
Accessor gtk:settings-gtk-titlebar-middle-click (object)
Syntax:
(gtk:settings-gtk-titlebar-middle-click object) => setting
(setf (gtk:settings-gtk-titlebar-middle-click object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with an action
Details:
Accessor of the gtk-titlebar-middle-click slot of the gtk:settings class. This setting determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
See also:
2023-8-30
Accessor gtk:settings-gtk-titlebar-right-click (object)
Syntax:
(gtk:settings-gtk-titlebar-right-click object) => setting
(setf (gtk:settings-gtk-titlebar-right-click object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with an action
Details:
Accessor of the gtk-titlebar-right-click slot of the gtk:settings class. This setting determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are "minimize", "toggle-maximize", "menu", "lower" or "none".
See also:
2023-8-30
Accessor gtk:settings-gtk-xft-antialias (object)
Syntax:
(gtk:settings-gtk-xft-antialias object) => setting
(setf (gtk:settings-gtk-xft-antialias object) setting)
Arguments:
object -- a gtk:settings object
setting -- a boolean whether to antialias Xft fonts
Details:
Accessor of the gtk-xft-antialias slot of the gtk:settings class. Whether to antialias Xft fonts: 0 = no, 1 = yes, -1 = default.
See also:
2023-8-30
Accessor gtk:settings-gtk-xft-dpi (object)
Syntax:
(gtk:settings-gtk-xft-dpi object) => setting
(setf (gtk:settings-gtk-xft-dpi object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer with the resolution for Xft
Details:
Accessor of the gtk-xft-dpi slot of the gtk:settings class. Resolution for Xft, in 1024 * dots/inch. -1 to use default value.
See also:
2023-8-30
Accessor gtk:settings-gtk-xft-hinting (object)
Syntax:
(gtk:settings-gtk-xft-hinting object) => setting
(setf (gtk:settings-gtk-xft-hinting object) setting)
Arguments:
object -- a gtk:settings object
setting -- an integer whether to hint Xft fonts
Details:
Accessor of the gtk-xft-hinting slot of the gtk:settings class. Whether to hint Xft fonts: 0 = no, 1 = yes, -1 = default.
See also:
2023-8-30
Accessor gtk:settings-gtk-xft-hintstyle (object)
Syntax:
(gtk:settings-gtk-xft-hintstyle object) => setting
(setf (gtk:settings-gtk-xft-hintstyle object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the deegree of hinting
Details:
Accessor of the gtk-xft-hintstyle slot of the gtk:settings class. What degree of hinting to use: hintnone, hintslight, hintmedium, or hintfull.
See also:
2023-8-30
Accessor gtk:settings-gtk-xft-rgba (object)
Syntax:
(gtk:settings-gtk-xft-rgba object) => setting
(setf (gtk:settings-gtk-xft-rgba object) setting)
Arguments:
object -- a gtk:settings object
setting -- a string with the type of subpixel antialiasing
Details:
Accessor of the gtk-xft-rgba slot of the gtk:settings class. Type of subpixel antialiasing: none, rgb, bgr, vrgb, vbgr.
See also:
2023-8-30
Function gtk:settings-default ()
Returns:
The gtk:settings object. If there is no default display, then returns nil.
Details:
Gets the gtk:settings object for the default GDK display, creating it if necessary. See the gtk:settings-for-display function.
See also:
2024-6-2
Function gtk:settings-for-display (screen)
Arguments:
display -- a gdk:display object
Returns:
The gtk:settings object.
Details:
Gets the gtk:settings object for display, creating it if necessary.
See also:
#2023-8-30
Function gtk:settings-reset-property (settings name)
Arguments:
settings -- a gtk:settings object
name -- a string with the name of the setting to reset
Details:
Undoes the effect of calling the g:object-property function to install an application-specific value for a setting. After this call, the setting will again follow the session-wide value for this setting.
See also:
2023-8-30

Standard Enumerations

GEnum gtk:align
Declaration:
(gobject:define-genum "GtkAlign" align
  (:export t
   :type-initializer "gtk_align_get_type")
  (:fill 0)
  (:start 1)
  (:end 2)
  (:center 3)
  #+gtk-4-12
  (:baseline-fill 4)
  #-gtk-4-12
  (:baseline 4)
  #+gtk-4-12
  (:baseline-center 5))  
Values:
:fill
Stretch to fill all space if possible, center if no meaningful way to stretch.
:start
Snap to left or top side, leaving space on right or bottom.
:end
Snap to right or bottom side, leaving space on left or top.
:center
Center natural width of widget inside the allocation.
:baseline-fill
A different name for baseline. Since 4.12
:baseline
Align the widget according to the baseline. Deprecated 4.12: Use :baseline-fill instead.
:baseline-center
Stretch to fill all space, but align the baseline. Since 4.12
Details:
Controls how a widget deals with extra space in a single dimension. Alignment only matters if the widget receives a "too large" allocation, for example if you packed the widget with the hexpand property inside a gtk:box widget, then the widget might get extra space. If you have for example a 16 x 16 icon inside a 32 x 32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space.

Note that in horizontal context the :start and :end values are interpreted relative to text direction.

The :baseline support is optional for containers and widgets, and it is only supported for vertical alignment. The :baseline-center and :baseline-fill values are treated similar to the :center and :fill values, except that it positions the widget to line up the baselines, where that is supported.
See also:
2024-4-19
GEnum gtk:baseline-position
Declaration:
(gobject:define-genum "GtkBaselinePosition" baseline-position
  (:export t
   :type-initializer "gtk_baseline_position_get_type")
  (:top 0)
  (:center 1)
  (:bottom 2))  
Values:
:top
Align the baseline at the top.
:center
Center the baseline.
:bottom
Align the baseline at the bottom.
Details:
Baseline position in a row of widgets. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of vertical space in the row is taller than the total requested height of the baseline aligned children then it can use a gtk:baseline-position value to select where to put the baseline inside the extra available space.
See also:
2024-4-7
GEnum gtk:delete-type
Declaration:
(gobject:define-genum "GtkDeleteType" delete-type
  (:export t
   :type-initializer "gtk_delete_type_get_type")
  (:chars 0)
  (:word-ends 1)
  (:words 2)
  (:display-lines 3)
  (:display-line-ends 4)
  (:paragraph-ends 5)
  (:paragraphs 6)
  (:whitespace 7))  
Values:
:chars
Delete characters.
:word-ends
Delete only the portion of the word to the left/right of cursor if we are in the middle of a word.
:words
Delete words.
:display-lines
Delete display-lines. Display-lines refers to the visible lines, with respect to to the current line breaks. As opposed to paragraphs, which are defined by line breaks in the input.
:display-line-ends
Delete only the portion of the display-line to the left/right of cursor.
:paragraph-ends
Delete to the end of the paragraph. Like C-k in Emacs (or its reverse).
:paragraphs
Delete entire line. Like C-k in pico.
:whitespace
Delete only whitespace. Like M-\ in Emacs.
Details:
The values of this enumeration are passed as an argument to various keybinding signals for deleting text.
See also:
2024-4-24
GEnum gtk:direction-type
Declaration:
(gobject:define-genum "GtkDirectionType" direction-type
  (:export t
   :type-initializer "gtk_direction_type_get_type")
  (:tab-forward 0)
  (:tab-backward 1)
  (:up 2)
  (:down 3)
  (:left 4)
  (:right 5))  
Values:
:tab-forward
Move forward.
:tab-backward
Move backward.
:up
Move up.
:down
Move down.
:left
Move left.
:right
Move right.
Details:
Focus movement types.
2024-4-24
GEnum gtk:icon-size
Declaration:
(gobject:define-genum "GtkIconSize" icon-size
  (:export t
   :type-initializer "gtk_icon_size_get_type")
  (:inherit 0)
  (:normal 1)
  (:large 2))  
Values:
:inherit
Keep the size of the parent element.
:normal
Size similar to text size.
:large
Large size, for example in an icon view.
Details:
Built-in icon sizes. Icon sizes default to being inherited. Where they cannot be inherited, text size is the default.

All widgets which use the gtk:icon-size enumeration set the .normal-icons or .large-icons style classes correspondingly, and let themes determine the actual size to be used with the -gtk:icon-size CSS property.
See also:
2023-9-20
GEnum gtk:response-type
Declaration:
(gobject:define-genum "GtkResponseType" response-type
  (:export t
   :type-initializer "gtk_response_type_get_type")
  (:none -1)
  (:reject -2)
  (:accept -3)
  (:delete-event -4)
  (:ok -5)
  (:cancel -6)
  (:close -7)
  (:yes -8)
  (:no -9)
  (:apply -10)
  (:help -11))  
Values:
:none
Returned if an action widget has no response ID, or if the dialog gets programmatically hidden or destroyed.
:reject
Generic response ID, not used by GTK dialog.
:accept
Generic response ID, not used by GTK dialog.
:delete-event
Returned if the dialog is deleted.
:ok
Returned by OK buttons in GTK dialog.
:cancel
Returned by Cancel buttons in GTK dialog.
:close
Returned by Close buttons in GTK dialog.
:yes
Returned by Yes buttons in GTK dialog.
:no
Returned by No buttons in GTK dialog.
:apply
Returned by Apply buttons in GTK dialog.
:help
Returned by Help buttons in GTK dialog.
Details:
Predefined values for use as response IDs in the gtk:dialog-add-button function. All predefined values are negative, GTK leaves positive values for application defined response IDs.
See also:
2024-4-24
Function gtk:response-type-keyword (response)
Arguments:
response -- an integer with the response value of the gtk:response-type enumeration
Returns:
The keyword for the given response value.
Details:
The gtk:response-type-keyword function is an utility function which returns the corresponding keyword for an integer of the gtk:response-type enumeration.
Notes:
This is a helper function in the Lisp binding which uses the cffi:foreign-enum-keyword function to get the keyword for the integer value of the enumeration.
See also:
2024-11-10
GEnum gtk:sensitivity-type
Declaration:
(gobject:define-genum "GtkSensitivityType" sensitivity-type
  (:export t
   :type-initializer "gtk_sensitivity_type_get_type")
  (:auto 0)
  (:on 1)
  (:off 2))  
Values:
:auto
The control is made insensitive if no action can be triggered.
:on
The control is always sensitive.
:off
The control is always insensitive.
Details:
Determines how GTK handles the sensitivity of various controls, such as combo box buttons.
See also:
2024-4-7
GEnum gtk:text-direction
Declaration:
(gobject:define-genum "GtkTextDirection" text-direction
  (:export t
   :type-initializer "gtk_text_direction_get_type")
  (:none 0)
  (:ltr 1)
  (:rtl 2))  
Values:
:none
No direction.
:ltr
Left to right text direction.
:rtl
Right to left text direction.
Details:
Reading directions for text.
See also:
2024-3-24
GEnum gtk:justification
Declaration:
(gobject:define-genum "GtkJustification" justification
  (:export t
   :type-initializer "gtk_justification_get_type")
  (:left 0)
  (:right 1)
  (:center 2)
  (:fill 3))  
Values:
:left
The text is placed at the left edge of the label.
:right
The text is placed at the right edge of the label.
:center
The text is placed in the center of the label.
:fill
The text is distributed across the label.
Details:
Used for justifying the text inside a gtk:label widget. See the justify property.
See also:
2024-4-24
GEnum gtk:message-type
Declaration:
(gobject:define-genum "GtkMessageType" message-type
  (:export t
   :type-initializer "gtk_message_type_get_type")
  (:info 0)
  (:warning 1)
  (:question 2)
  (:error 3)
  (:other 4))  
Values:
:info
Informational message.
:warning
Non-fatal warning message.
:question
Question requiring a choice.
:error
Fatal error message.
:other
None of the above.
Details:
The type of message being displayed in the message dialog.
See also:
2024-4-24
GEnum gtk:movement-step
Declaration:
(gobject:define-genum "GtkMovementStep" movement-step
  (:export t
   :type-initializer "gtk_movement_step_get_type")
  (:logical-positions 0)
  (:visual-positions 1)
  (:words 2)
  (:display-lines 3)
  (:display-line-ends 4)
  (:paragraphs 5)
  (:paragraph-ends 6)
  (:pages 7)
  (:buffer-ends 8)
  (:horizontal-pages 9))  
Values:
:logical-positions
Move forward or back by graphemes.
:visual-positions
Move left or right by graphemes.
:words
Move forward or back by words.
:display-lines
Move up or down lines (wrapped lines).
:display-line-ends
Move to either end of a line.
:paragraphs
Move up or down paragraphs (newline-ended lines).
:paragraph-ends
Move to either end of a paragraph.
:pages
Move by pages.
:buffer-ends
Move to ends of the buffer.
:horizontal-pages
Move horizontally by pages.
Details:
The values of this enumeration are passed to various keybinding signals for moving the cursor position.
See also:
2024-4-24
GEnum gtk:natural-wrap-mode
Declaration:
(gobject:define-genum "GtkNaturalWrapMode" natural-wrap-mode
  (:export t
   :type-initializer "gtk_natural_wrap_mode_get_type")
  (:inherit 0)
  (:none 1)
  (:word 2))  
Values:
:inherit
Inherit the minimum size request. In particular, this should be used with the :char value of the pango:wrap-mode enumeration.
:none
Try not to wrap the text. This mode is the closest to the behavior of GTK 3 but can lead to a wide label leaving lots of empty space below the text.
:word
Attempt to wrap at word boundaries. This is useful in particular when using the :word-char value of the pango:wrap-mode enumeration as the wrap mode.
Details:
Options for selecting a different wrap mode for natural size requests. See for example the natural-wrap-mode property.

Since 4.6
See also:
2024-4-24
GEnum gtk:orientation
Declaration:
(gobject:define-genum "GtkOrientation" orientation
  (:export t
   :type-initializer "gtk_orientation_get_type")
  (:horizontal 0)
  (:vertical 1))  
Values:
:horizontal
The object is in horizontal orientation.
:vertical
The object is in vertical orientation.
Details:
Represents the orientation of widgets and other objects which can be switched between horizontal and vertical orientation on the fly. Typical examples are the gtk:box widget or the gtk:gesture-pan object.
See also:
2024-4-1
GEnum gtk:overflow
Declaration:
(gobject:define-genum "GtkOverflow" overflow
  (:export t
   :type-initializer "gtk_overflow_get_type")
  (:visible 0)
  (:hidden 1))  
Values:
:visible
No change is applied. Content is drawn at the specified position.
:hidden
Content is clipped to the bounds of the area. Content outside the area is not drawn and cannot be interacted with.
Details:
Defines how content overflowing a given area should be handled. This is used in the gtk:widget-overflow function. The overflow property is modeled after the CSS overflow property, but implements it only partially.
See also:
2024-4-24
GEnum gtk:pack-type
Declaration:
(gobject:define-genum "GtkPackType" pack-type
  (:export t
   :type-initializer "gtk_pack_type_get_type")
  (:start 0)
  (:end 1))  
Values:
:start
The child is packed into the start of the widget.
:end
The child is packed into the end of the widget.
Details:
Represents the packing location of the child widget in its parent. See the gtk:window-controls widget.
See also:
2024-4-24
GEnum gtk:position-type
Declaration:
(gobject:define-genum "GtkPositionType" position-type
  (:export t
   :type-initializer "gtk_position_type_get_type")
  (:left 0)
  (:right 1)
  (:top 2)
  (:bottom 3))  
Values:
:left
The feature is at the left edge.
:right
The feature is at the right edge.
:top
The feature is at the top edge.
:bottom
The feature is at the bottom edge.
Details:
Describes which edge of a widget a certain feature is positioned at. For example, see the tabs of a gtk:notebook widget, or the label of a gtk:scale widget.
See also:
2024-4-24
GEnum gtk:scroll-type
Declaration:
(gobject:define-genum "GtkScrollType" scroll-type
  (:export t
   :type-initializer "gtk_scroll_type_get_type")
  (:none 0)
  (:jump 1)
  (:step-backward 2)
  (:step-forward 3)
  (:page-backward 4)
  (:page-forward 5)
  (:step-up 6)
  (:step-down 7)
  (:page-up 8)
  (:page-down 9)
  (:step-left 10)
  (:step-right 11)
  (:page-left 12)
  (:page-right 13)
  (:start 14)
  (:end 15))  
Details:
The scrolling types of this enumeration are a parameter for signal handlers in various widgets such as the gtk:spin-button, gtk:scrolled-window, or gtk:combo-box widget.
See also:
2024-4-24
GEnum gtk:selection-mode
Declaration:
(gobject:define-genum "GtkSelectionMode" gtk:selection-mode
  (:export t
   :type-initializer "gtk_selection_mode_get_type")
  (:none 0)
  (:single 1)
  (:browse 2)
  (:multiple 3))  
Values:
:none
No selection is possible.
:single
Zero or one element may be selected.
:browse
Exactly one element is selected. In some circumstances, such as initially or during a search operation, it is possible for no element to be selected with the :browse value. What is really enforced is that the user cannot deselect a currently selected element except by selecting another element.
:multiple
Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and the Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements.
Details:
Used to control what selections users are allowed to make.
See also:
2024-4-24
GEnum gtk:wrap-mode
Declaration:
(gobject:define-genum "GtkWrapMode" wrap-mode
  (:export t
   :type-initializer "gtk_wrap_mode_get_type")
  (:none 0)
  (:char 1)
  (:word 2)
  (:word-char 3))  
Values:
:none
Do not wrap lines, just make the text area wider.
:char
Wrap text, breaking lines anywhere the cursor can appear between characters, usually. If you want to be technical, between graphemes, see the pango:log-attrs function.
:word
Wrap text, breaking lines in between words.
:word-char
Wrap text, breaking lines in between words, or if that is not enough, also between graphemes.
Details:
Describes a type of line wrapping.
See also:
2024-4-24
GEnum gtk:sort-type
Declaration:
(gobject:define-genum "GtkSortType" sort-type
  (:export t
   :type-initializer "gtk_sort_type_get_type")
  (:ascending 0)
  (:descending 1))  
Values:
:ascending
Sorting is in ascending order.
:descending
Sorting is in descending order.
Details:
Determines the direction of a sort.
See also:
2024-4-24
GEnum gtk:ordering
Declaration:
(gobject:define-genum "GtkOrdering" ordering
  (:export t
   :type-initializer "gtk_ordering_get_type")
  (:smaller -1)
  (:equal 0)
  (:larger 1))  
Values:
:smaller
The first value is smaller than the second.
:equal
The two values are equal.
:larger
The first value is larger than the second.
Details:
Describes the way two values can be compared. These values can be used with the g:compare-data-func callback function. However, the g:compare-data-func function is allowed to return any integers. For converting such a value to a gtk:ordering value, use the gtk:ordering-from-cmpfunc function.
See also:
2024-10-18
GEnum gtk:size-request-mode
Declaration:
(gobject:define-genum "GtkSizeRequestMode" size-request-mode
  (:export t
   :type-initializer "gtk_size_request_mode_get_type")
  (:height-for-width 0)
  (:width-for-height 1)
  (:constant-size 2))  
Values:
:height-for-width
Prefer height-for-width geometry management.
:width-for-height
Prefer width-for-height geometry management.
:constant-size
Do not trade height-for-width or width-for-height geometry management.
Details:
Specifies a preference for height-for-width or width-for-height geometry management.
See also:
2024-4-24
GFlags gtk:state-flags
Declaration:
(gobject:define-gflags "GtkStateFlags" state-flags
  (:export t
   :type-initializer "gtk_state_flags_get_type")
  (:normal 0)
  (:active        #.(ash 1 0))
  (:prelight      #.(ash 1 1))
  (:selected      #.(ash 1 2))
  (:insensitive   #.(ash 1 3))
  (:inconsistent  #.(ash 1 4))
  (:focused       #.(ash 1 5))
  (:backdrop      #.(ash 1 6))
  (:dir-ltr       #.(ash 1 7))
  (:dir-rtl       #.(ash 1 8))
  (:link          #.(ash 1 9))
  (:visited       #.(ash 1 10))
  (:checked       #.(ash 1 11))
  (:drop-active   #.(ash 1 12))
  (:focus-visible #.(ash 1 13))
  (:focus-within  #.(ash 1 14)))  
Values:
:normal
State during normal operation.
:active
Widget is active.
:prelight
Widget has a mouse pointer over it.
:selected
Widget is selected.
:insensitive
Widget is insensitive.
:inconsistent
Widget is inconsistent.
:focused
Widget has the keyboard focus.
:backdrop
Widget is in a background toplevel window.
:dir-ltr
Widget is in left-to-right text direction.
:dir-rtl
Widget is in right-to-left text direction.
:link
Widget is a link.
:visited
The location the widget points to has already been visited.
:checked
Widget is checked.
:drop-active
Widget is highlighted as a drop target for DND.
:focus-visible
Widget has the visible focus.
:focus-within
Widget contains the keyboard focus.
Details:
Describes a widget state. Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses different names.
See also:
2024-4-24
GEnum gtk:border-style
Declaration:
(gobject:define-genum "GtkBorderStyle" border-style
  (:export t
   :type-initializer "gtk_border_style_get_type")
  :none
  :hidden
  :solid
  :inset
  :outset
  :dotted
  :dashed
  :double
  :groove
  :ridge)  
Values:
:none
No visible border.
:hidden
Same as the :none value.
:solid
A single line segment.
:inset
Looks as if the content is sunken into the canvas.
:outset
Looks as if the content is coming out of the canvas.
:dotted
A series of round dots.
:dashed
A series of square-ended dashes.
:double
Two parrallel lines with some space between them.
:groove
Looks as if it were carved in the canvas.
:ridge
Looks as if it were coming out of the canvas.
Details:
Describes how the border of a UI element should be rendered.
See also:
2024-4-24
GEnum gtk:input-purpose
Declaration:
(gobject:define-genum "GtkInputPurpose" input-purpose
  (:export t
   :type-initializer "gtk_input_purpose_get_type")
  (:free-form 0)
  (:alpha 1)
  (:digits 2)
  (:number 3)
  (:phone 4)
  (:url 5)
  (:email 6)
  (:name 7)
  (:password 8)
  (:pin 9)
  (:terminal 10))  
Values:
:free-form
Allow any character.
:alpha
Allow only alphabetic characters.
:digits
Allow only digits.
:number
Edited field expects numbers.
:phone
Edited field expects phone number.
:url
Edited field expects URL.
:email
Edited field expects email address.
:name
Edited field expects the name of a person.
:password
Like :free-form, but characters are hidden.
:pin
Like :digits, but characters are hidden.
:terminal
Allow any character, in addition to control codes.
Details:
Describes primary purpose of the input widget. This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user.

Note that the purpose is not meant to impose a totally strict rule about allowed characters, and does not replace input validation. It is fine for an on-screen keyboard to let the user override the character set restriction that is expressed by the purpose. The application is expected to validate the text entry contents, even if it specified a purpose.

The difference between the :digits and :number values is that the former accepts only digits while the latter also some punctuation, like commas or points, plus, minus, and 'e' or 'E' as in 3.14E+000.

This enumeration may be extended in the future. Input methods should interpret unknown values as 'free form'.
See also:
2024-4-24
GFlags gtk:input-hints
Declaration:
(gobject:define-gflags "GtkInputHints" input-hints
  (:export t
   :type-initializer "gtk_input_hints_get_type")
  (:none 0)
  (:spellcheck          #.(ash 1 0))
  (:no-spellcheck       #.(ash 1 1))
  (:word-completion     #.(ash 1 2))
  (:lowercase           #.(ash 1 3))
  (:uppercase-chars     #.(ash 1 4))
  (:uppercase-words     #.(ash 1 5))
  (:uppercase-sentences #.(ash 1 6))
  (:inhibit-osk         #.(ash 1 7))
  (:vertical-writing    #.(ash 1 8))
  (:emoji               #.(ash 1 9))
  (:no-emoji            #.(ash 1 10))
  (:private             #.(ash 1 11)))  
Values:
:none
No special behaviour suggested.
:spellcheck
Suggest checking for typos.
:no-spellcheck
Suggest not checking for typos.
:word-completion
Suggest word completion.
:lowercase
Suggest to convert all text to lowercase.
:uppercase-chars
Suggest to capitalize all text.
:uppercase-words
Suggest to capitalize the first character of each word.
:uppercase-sentences
Suggest to capitalize the first word of each sentence.
:inhibit-osk
Suggest to not show an onscreen keyboard, for example, for a calculator that already has all the keys.
:vertical-writing
The text is vertical.
:emoji
Suggest offering Emoji support.
:no-emoji
Suggest not offering Emoji support.
:private
Request that the input method should not update personalized data (like typing history).
Details:
Describes hints that might be taken into account by input methods or applications. Note that input methods may already tailor their behaviour according to the gtk:input-purpose value of the text entry.

Some common sense is expected when using these flags - mixing :lowercase with any of the uppercase hints makes no sense.

This flags may be extended in the future. Input methods should ignore unknown values.
See also:
2024-4-24
GFlags gtk:pick-flags
Declaration:
(gobject:define-gflags "GtkPickFlags" pick-flags
  (:export t
   :type-initializer "gtk_pick_flags_get_type")
  (:default 0)
  (:insensitive #.(ash 1 0))
  (:non-targetable #.(ash 1 1)))  
Values:
:default
The default behavior, include widgets that are receiving events.
:insensitive
Include widgets that are insensitive.
:non-targetable
Include widgets that are marked as non-targetable. See the can-target property.
Details:
Flags that influence the behavior of the gtk:widget-pick function.
See also:
2024-3-8
GEnum gtk:constraint-relation
Declaration:
(gobject:define-genum "GtkConstraintRelation" constraint-relation
  (:export t
   :type-initializer "gtk_constraint_relation_get_type")
  (:le -1)
  (:eq 0)
  (:ge 1))  
Values:
:le
Less than, or equal
:eq
Equal
:ge
Greater than, or equal
Details:
The relation between two terms of a constraint.
2024-4-24
GEnum gtk:constraint-strength
Declaration:
(gobject:define-genum "GtkConstraintStrength" constraint-strength
  (:export t
   :type-initializer "gtk_constraint_strength_get_type")
  (:required 1001001000)
  (:strong   1000000000)
  (:medium   1000)
  (:weak     1))  
Values:
:required
The constraint is required towards solving the layout.
:strong
A strong constraint.
:medium
A medium constraint.
:weak
A weak constraint.
Details:
The strength of a constraint, expressed as a symbolic constant. The strength of a gtk:constraint widget can be expressed with any positive integer. The values of this enumeration can be used for readability.
See also:
2024-4-24
GEnum gtk:constraint-attribute
Declaration:
(gobject:define-genum "GtkConstraintAttribute" constraint-attribute
  (:export t
   :type-initializer "gtk_constraint_attribute_get_type")
  :none
  :left
  :right
  :top
  :bottom
  :start
  :end
  :width
  :height
  :center-x
  :center-y
  :baseline)  
Values:
:none
No attribute, used for constant relations.
:left
The left edge of a widget, regardless of text direction.
:right
The right edge of a widget, regardless of text direction.
:top
The top edge of a widget.
:bottom
The bottom edge of a widget.
:start
The leading edge of a widget, depending on text direction. Equivalent to the :left value for LTR languages, and the :right value for RTL ones.
:end
The trailing edge of a widget, depending on text direction. Equivalent to the :right value for LTR languages, and the :left value for RTL ones.
:width
The width of a widget.
:height
The height of a widget.
:center-x
The center of a widget, on the horizontal axis.
:center-y
The center of a widget, on the vertical axis.
:baseline
The baseline of a widget.
Details:
The widget attributes that can be used when creating a gtk:constraint widget.
See also:
2024-4-24
GEnum gtk:constraint-vfl-parser-error
Declaration:
(gobject:define-genum "GtkConstraintVflParserError" constraint-vfl-parser-error
  (:export t
   :type-initializer "gtk_constraint_vfl_parser_error")
  :invalid-symbol
  :invalid-attribute
  :invalid-view
  :invalid-metric
  :invalid-priority
  :invalid-relation)  
Values:
:invalid-symbol
Invalid or unknown symbol.
:invalid-attribute
Invalid or unknown attribute.
:invalid-view
Invalid or unknown view.
:invalid-metric
Invalid or unknown metric.
:invalid-priority
Invalid or unknown priority.
:invalid-relation
Invalid or unknown relation.
Details:
Domain for VFL parsing errors.
2024-4-24
GEnum gtk:symbolic-color
Declaration:
(gobject:define-genum "GtkSymbolicColor" symbolic-color
  (:export t
   :type-initializer "gtk_symbolic_color_get_type")
  (:foreground 0)
  (:error 1)
  (:warning 2)
  (:success 3))  
Values:
:foreground
The default foreground color.
:error
Indication color for errors.
:warning
Indication color for warnings.
:success
Indication color for success.
Details:
The indexes of colors passed to symbolic color rendering, such as the GtkSymbolicPaintable::snapshot_symbolic virtual function.

Since 4.6
2024-4-24
GEnum gtk:accessible-role
Declaration:
(gobject:define-genum "GtkAccessibleRole" accessible-role
  (:export t
   :type-initializer "gtk_accessible_role_get_type")
  :alert
  :alert-dialog
  :banner
  :button
  :caption
  :cell
  :checkbox
  :column-header
  :combo-box
  :command
  :composite
  :dialog
  :document
  :feed
  :form
  :generic
  :grid
  :grid-cell
  :group
  :heading
  :img
  :input
  :label
  :landmark
  :legend
  :link
  :list
  :list-box
  :list-item
  :log
  :main
  :marquee
  :math
  :meter
  :menu
  :menu-bar
  :menu-item
  :menu-item-checkbox
  :menu-item-radio
  :navigation
  :none
  :note
  :option
  :presentation
  :progress-bar
  :radio
  :radio-group
  :range
  :region
  :row
  :row-group
  :row-header
  :scrollbar
  :search
  :search-box
  :section
  :section-head
  :select
  :separator
  :slider
  :spin-button
  :status
  :structure
  :switch
  :tab
  :table
  :tab-list
  :tab-panel
  :text-box
  :time
  :timer
  :toolbar
  :tooltip
  :tree
  :tree-grid
  :tree-item
  :widget
  :window
  #+gtk-4-10
  :toggle-button
  #+gtk-4-12
  :application
  #+gtk-4-14
  :paragraph
  #+gtk-4-14
  :block-quote
  #+gtk-4-14
  :article
  #+gtk-4-14
  :comment
  #+gtk-4-14
  :terminal)  
Values:
:alert
An element with important, and usually time-sensitive, information.
:alert-dialog
A type of dialog that contains an alert message.
:banner
Unused
:button
An input element that allows for user-triggered actions when clicked or pressed.
:caption
Unused
:cell
Unused
:checkbox
A checkable input element that has three possible values: "true", "false", or "mixed".
:column-header
A header in a columned list.
:combo-box
An input that controls another element, such as a list or a grid, that can dynamically pop up to help the user set the value of the input.
:command
Abstract role.
:composite
Abstract role.
:dialog
A dialog is a window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response.
:document
Unused
:feed
Unused
:form
Unused
:generic
Unused
:grid
A grid of items.
:grid-cell
An item in a grid or tree grid.
:group
An element that groups multiple widgets. GTK uses this role for various containers, like the gtk:box, gtk:viewport, and gtk:header-bar widgets.
:heading
Unused
:img
An image.
:input
Abstract role.
:label
A visible name or caption for a user interface component.
:landmark
Abstract role.
:legend
Unused
:link
A clickable link.
:list
A list of items.
:list-box
Unused
:list-item
An item in a list.
:log
Unused
:main
Unused
:marquee
Unused
:math
Unused
:meter
An element that represents a value within a known range.
:menu
A menu.
:menu-bar
A menubar.
:menu-item
An item in a menu.
:menu-item-checkbox
A check item in a menu.
:menu-item-radio
A radio item in a menu.
:navigation
Unused
:none
An element that is not represented to accessibility technologies.
:note
Unused
:option
Unused
:presentation
An element that is not represented to accessibility technologies.
:progress-bar
An element that displays the progress status for tasks that take a long time.
:radio
A checkable input in a group of radio roles, only one of which can be checked at a time.
:radio-group
Unused
:range
Abstract role.
:region
Unused
:row
A row in a columned list.
:row-group
Unused
:row-header
Unused
:scrollbar
A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.
:search
Unused
:search-box
A type of textbox intended for specifying search criteria.
:section
Abstract role.
:section-head
Abstract role.
:select
Abstract role.
:separator
A divider that separates and distinguishes sections of content or groups of menuitems.
:slider
A user input where the user selects a value from within a given range.
:spin-button
A form of range that expects the user to select from among discrete choices.
:status
Unused
:structure
Abstract role.
:switch
A type of checkbox that represents on/off values, as opposed to checked/unchecked values.
:tab
An item in a list of tab used for switching pages.
:table
Unused
:tab-list
A list of tabs for switching pages.
:tab-panel
A page in a notebook or stack.
:text-box
A type of input that allows free-form text as its value.
:time
Unused
:timer
Unused
:toolbar
Unused
:tooltip
Unused
:tree
Unused
:tree-grid
A treeview-like, columned list.
:tree-item
Unused
:widget
An interactive component of a graphical user interface. This is the role that GTK uses by default for widgets.
:window
An application window.
:toggle-button
A type of push button which stays pressed until depressed by a second activation. Since: 4.10
:application
A toplevel element of a graphical user interface. This is the role that GTK uses by default for windows. Since 4.12
:paragraph
A paragraph of content. Since 4.14
:block-quote
A section of content that is quoted from another source. Since 4.14
:article
A section of a page that consists of a composition that forms an independent part of a document, page, or site. Since 4.14
:comment
A comment contains content expressing reaction to other content. Since 4.14
:terminal
A virtual terminal. Since 4.14
Details:
The accessible role for a gtk:accessible implementation. Abstract roles are only used as part of the ontology. Application developers must not use abstract roles in their code.
See also:
2024-5-25
GEnum gtk:accessible-state
Declaration:
(gobject:define-genum "GtkAccessibleState" gtk:accessible-state
  (:export t
   :type-initializer "gtk_accessible_state_get_type")
   :busy
   :checked
   :disabled
   :expanded
   :hidden
   :invalid
   :pressed
   :selected
   #+gtk-4-12
   :visited)  
Values:
:busy
A "busy" state. This state has boolean values.
:checked
A "checked" state. Indicates the current state of a gtk:check-button widget. Value type: gtk:accessible-tristate enumeration
:disabled
A "disabled" state. Corresponds to the sensitive property on the gtk:widget object. It indicates a UI element that is perceivable, but not editable or operable. Value type: boolean
:expanded
An "expanded" state. Corresponds to the expanded property on the gtk:expander widget. Value type: boolean or undefined
:hidden
A "hidden" state. Corresponds to the visible property on the gtk:widget object. You can use this state explicitly on UI elements that should not be exposed to an assistive technology. See also the :disabled value. Value type: boolean
:invalid
An "invalid" state. Set when a widget is showing an error. Value type: gtk:accessible-invalid-state enumeration
:pressed
A "pressed" state. Indicates the current state of a gtk:toggle-button widget. Value type: gtk:accessible-tristate enumeration
:selected
A "selected" state. Set when a widget is selected. Value type: boolean or undefined
:visited
Indicates that a widget with the :link role has been visited. Value type: boolean. Since 4.12
Details:
The possible accessible states of a gtk:accessible widget.
See also:
2024-4-24
GEnum gtk:accessible-property
Declaration:
(gobject:define-genum "GtkAccessibleProperty" accessible-property
  (:export t
   :type-initializer "gtk_accessible_property_get_type")
  :autocomplete
  :description
  :has-popup
  :key-shortcuts
  :label
  :level
  :modal
  :multi-line
  :multi-selectable
  :orientation
  :placeholder
  :read-only
  :required
  :role-description
  :sort
  :value-max
  :value-min
  :value-now
  :value-text
  :help-text)  
Values:
:auto-complete
Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. Value type: gtk:accessible-autocomplete enumeration
:description
Defines a string value that describes or annotates the current element. Value type: string
:has-popup
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
:key-shortcuts
Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. Value type: string
:label
Defines a string value that labels the current element. Value type: string
:level
Defines the hierarchical level of an element within a structure. Value type: integer
:modal
Indicates whether an element is modal when displayed. Value type: boolean
:multi-line
Indicates whether a text box accepts multiple lines of input or only a single line. Value type: boolean
:multi-selectable
Indicates that the user may select more than one item from the current selectable descendants. Value type: boolean
:orientation
Indicates whether the orientation of the element is horizontal, vertical, or unknown/ambiguous. Value type: gtk:orientation enumeration
:placeholder
Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. Value type: string
:read-only
Indicates that the element is not editable, but is otherwise operable. Value type: boolean
:required
Indicates that user input is required on the element before a form may be submitted. Value type: boolean
:role-description
Defines a human-readable, author-localized description for the role of an element. Value type: string
:sort
Indicates if items in a table or grid are sorted in ascending or descending order. Possible property values are in the gtk:accessible-sort enumeration. Value type: gtk:accessible-sort enumeration
:value-max
Defines the maximum allowed value for a range widget. Value type: double
:value-min
Defines the minimum allowed value for a range widget. Value type: double
:value-now
Defines the current value for a range widget. Value type: double
:value-text
Defines the human readable text alternative of aria-valuenow for a range widget. Value type: string
:help-text
Defines a string value that provides a description of non-standard keyboard interactions of the current element. Value type: string. Since 4.16
Details:
The possible accessible properties of a gtk:accessible widget.
See also:
2024-10-13
GEnum gtk:accessible-relation
Declaration:
(gobject:define-genum "GtkAccessibleRelation" accessible-relation
  (:export t
   :type-initializer "gtk_accessible_relation_get_type")
  :active-descendant
  :col-count
  :col-index
  :col-index-text
  :col-span
  :controls
  :described-by
  :details
  :error-message
  :flow-to
  :labelled-by
  :owns
  :pos-in-set
  :row-count
  :row-index
  :row-index-text
  :row-span
  :set-size)  
Values:
:active-descendant
Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application. Value type: reference
:col-count
Defines the total number of columns in a table, grid, or treegrid. Value type: integer
:col-index
Defines a column index of the element or position with respect to the total number of columns within a table, grid, or treegrid. Value type: integer
:col-index-text
Defines a human readable text alternative of the :col-index value. Value type: string
:col-span
Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer
:controls
Identifies the element (or elements) whose contents or presence are controlled by the current element. Value type: reference
:described-by
Identifies the element (or elements) that describes the object. Value type: reference
:details
Identifies the element (or elements) that provide additional information related to the object. Value type: reference
:error-message
Identifies the element that provides an error message for an object. Value type: reference
:flow-to
Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference
:labelled-by
Identifies the element (or elements) that labels the current element. Value type: reference
:owns
Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between elements where the widget hierarchy cannot be used to represent the relationship. Value type: reference
:pos-in-set
Defines a number or position of the element in the current set of listitems or treeitems. Value type: integer
:row-count
Defines the total number of rows in a table, grid, or treegrid. Value type: integer
:row-index
Defines a row index or position of the element with respect to the total number of rows within a table, grid, or treegrid. Value type: integer
:row-index-text
Defines a human readable text alternative of aria-rowindex. Value type: string
:row-span
Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer
:set-size
Defines the number of items in the current set of listitems or treeitems. Value type: integer
Details:
The possible accessible relations of a gtk:accessible widget. Accessible relations can be references to other widgets, integers or strings.
See also:
2024-4-24
GEnum gtk:accessible-tristate
Declaration:
(gobject:define-genum "GtkAccessibleTristate" accessible-tristate
  (:export t
   :type-initializer "gtk_accessible_tristate_get_type")
  :false
  :true
  :mixed)  
Values:
:false
The state is "false".
:true
The state is "true".
:mixed
The state is "mixed".
Details:
The possible values for the :pressed accessible state. Note that the :false and :true values have the same values as false and true.
See also:
2024-4-24
GEnum gtk:accessible-invalid-state
Declaration:
(gobject:define-genum "GtkAccessibleInvalidState" accessible-invalid-state
  (:export t
   :type-initializer "gtk_accessible_invalid_state_get_type")
  :false
  :true
  :grammar
  :spelling)  
Values:
:false
There are no detected errors in the value.
:true
The value entered by the user has failed validation.
:grammar
A grammatical error was detected.
:spelling
A spelling error was detected.
Details:
The possible values for the :invalid accessible state. Note that the :false and :true values have the same values as false and true.
See also:
2024-4-24
GEnum gtk:accessible-autocomplete
Declaration:
(gobject:define-genum "GtkAccessibleAutocomplete" accessible-autocomplete
  (:export t
   :type-initializer "gtk_accessible_autocomplete_get_type")
  :none
  :inline
  :list
  :both)  
Values:
:none
Automatic suggestions are not displayed.
:inline
When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret.
:list
When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
:both
When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.
Details:
The possible values for the :autocomplete accessible property.
See also:
2024-4-24
GEnum gtk:accessible-sort
Declaration:
(gobject:define-genum "GtkAccessibleSort" accessible-sort
  (:export t
   :type-initializer "gtk_accessible_sort_get_type")
  :none
  :ascending
  :descending
  :other)  
Values:
:none
There is no defined sort applied to the column.
:ascending
Items are sorted in ascending order by this column.
:descending
Items are sorted in descending order by this column.
:other
A sort algorithm other than ascending or descending has been applied.
Details:
The possible values for the :sort accessible property.
See also:
2024-4-24
GEnum gtk:accessible-announcement-priority
Declaration:
(gobject:define-genum "GtkAccessibleAnnouncementPriority"
                      accessible-announcement-priority
  (:export t
   :type-initializer "gtk_accessible_announcement_priority_get_type")
  :low
  :medium
  :high)  
Values:
:low
The announcement is low priority, and might be read only on the request of the user.
:medium
The announcement is of medium priority, and is usually spoken at the next opportunity, such as at the end of speaking the current sentence or when the user pauses typing.
:hight
The announcement is of high priority, and is usually spoken immediately. Because an interruption might disorient users or cause them to not complete their current task, authors should not use high priority announcements unless the interruption is imperative. An example would be a notification about a critical battery power level.
Details:
The priority of an accessibility announcement. Since 4.14
See also:
2024-11-3

Filesystem utilities

Theming in GTK

GtkStyleProvider

Constant gtk:+priority-fallback+
Initial Value:
1
Details:
The priority used for default style information that is used in the absence of themes. Note that this is not very useful for providing default styling for custom style classes - themes are likely to override styling provided at this priority with catch-all * {...} rules.
See also:
2024-4-1
Constant gtk:+priority-theme+
Initial Value:
200
Details:
The priority used for style information provided by themes.
See also:
2024-4-1
Constant gtk:+priority-settings+
Initial Value:
400
Details:
The priority used for style information provided via the gtk:settings object. This priority is higher than the gtk:+priority-theme+ value to let settings override themes.
See also:
2024-4-1
Constant gtk:+priority-application+
Initial Value:
600
Details:
A priority that can be used when adding a gtk:style-provider object for application specific style information.
See also:
2024-4-1
Constant gtk:+priority-user+
Initial Value:
800
Details:
The priority used for the style information from the $XDG_CONFIG_HOME/gtk-4.0/gtk.css file. You should not use priorities higher than this, to give the user the last word.
See also:
2024-4-1
Interface gtk:style-provider
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:style-provider interface is an interface used to provide style information to a gtk:style-context object. See the gtk:style-context-add-provider-for-display function for adding style providers to a style context and the gtk:widget-add-provider function to add a style provider to the display of a widget.

GTK uses the gtk:style-provider implementation for CSS in the gtk:css-provider implementation.
Signal Details:
The "gtk-private-changed" signal
lambda (provider)    :run-last      
provider
The gtk:style-provider object which received the signal.
No description available.
See also:
2024-11-2

GtkCssLocation

CStruct gtk:css-location
Declaration:
(cffi:defcstruct css-location
  (bytes :size)
  (chars :size)
  (lines :size)
  (line-bytes :size)
  (line-chars :size))  
Values:
bytes
Number of bytes parsed since the beginning.
chars
Number of characters parsed since the beginning.
lines
Number of full lines that have been parsed. If you want to display this as a line number, you need to add 1 to this.
line-bytes
Number of bytes parsed since the last line break.
line-chars
Number of characters parsed since the last line break.
Slot Access Functions:
Details:
The gtk:css-location structure is used to present a location in a file or other source of data parsed by the CSS engine. The bytes and line-bytes offsets are meant to be used to programmatically match data. The lines and line-chars offsets can be used for printing the location in a file.

Note that the lines parameter starts from 0 and is increased whenever a CSS line break is encountered. CSS defines the C character sequences "\r\n", "\r", "\n" and "\f" as newlines. If your document uses different rules for line breaking, you might want run into problems here. See the gtk:css-section documentation of an example.
See also:
2025-2-25
Accessor gtk:css-location-bytes (location)
Syntax:
(gtk:css-location-bytes location) => bytes
Arguments:
location -- a gtk:css-location instance
bytes -- a number of the foreign type :size
Details:
Returns the number of bytes parsed since the beginning.
See also:
2025-2-25
Accessor gtk:css-location-chars (location)
Syntax:
(gtk:css-location-chars location) => chars
Arguments:
location -- a gtk:css-location instance
bytes -- a number of the foreign type :size
Details:
Returns the number of characters parsed since the beginning.
See also:
2025-2-25
Accessor gtk:css-location-lines (location)
Syntax:
(gtk:css-location-lines location) => lines
Arguments:
location -- a gtk:css-location instance
lines -- a number of the foreign type :size
Details:
Returns the number of full lines that have been parsed. If you want to display this as a line number, you need to add 1 to this.
See also:
2025-2-25
Accessor gtk:css-location-line-bytes (location)
Syntax:
(gtk:css-location-line-bytes location) => line-bytes
Arguments:
location -- a gtk:css-location instance
line-bytes -- a number of the foreign type :size
Details:
Returns the number of bytes parsed since the last line break.
See also:
2025-2-25
Accessor gtk:css-location-line-chars (location)
Syntax:
(gtk:css-location-line-chars location) => line-chars
Arguments:
location -- a gtk:css-location instance
line-chars -- a number of the foreign type :size
Details:
Returns the number of characters parsed since the last line break.
See also:
2025-2-25

GtkCssSection

GBoxed gtk:css-section
Declaration:
(glib:define-gboxed-opaque css-section "GtkCssSection"
  :export t
  :type-initializer "gtk_css_section_get_type"
  :alloc (error "GtkCssSection cannot be created from the Lisp side"))  
Returned by:
Details:
Defines a part of a CSS document. Because sections are nested into one another, you can use the gtk:css-section-parent function to get the containing region.
Examples:
Access the gtk:css-location and gtk:css-section structures in a "parsing-error" signal handler to mark an error in the parsed CSS file, which is loaded into text buffer.
(g:signal-connect provider "parsing-error"
        (lambda (provider section err)
          (declare (ignore provider err))
          (let* ((startloc (gtk:css-section-start-location section))
                 (start (gtk:text-buffer-iter-at-line-index
                                text
                                (gtk:css-location-lines startloc)
                                (gtk:css-location-line-bytes startloc)))
                 (endloc (gtk:css-section-end-location section))
                 (end (gtk:text-buffer-iter-at-line-index
                              text
                              (gtk:css-location-lines endloc)
                              (gtk:css-location-line-bytes endloc))))
            (gtk:text-buffer-apply-tag text "error" start end)
            gdk:+event-stop+)))    
See also:
2025-2-25
Function gtk:css-section-new (path start end)
Arguments:
path -- a pathname or namestring for the file this section refers to
start -- a gtk:css-location instance for the start location
end -- a gtk:css-location instance for the end location
Returns:
The new gtk:css-section instance.
Details:
Creates a new gtk:css-section instance referring to the section in the given path from the start location to the end location.
See also:
2025-2-25
Function gtk:css-section-new-with-bytes (path bytes start end)
Arguments:
path -- a pathname or namestring for the file this section refers to
bytes -- a g:bytes instance for the bytes this section refers to
start -- a gtk:css-location instance for the start location
end -- a gtk:css-location instance for the end location
Returns:
The new gtk:css-section instance.
Details:
Creates a new gtk:css-section instance referring to the section in the given path or the given bytes from the start location to the end location.

Since 4.16
See also:
#2025-2-25
Function gtk:css-section-to-string (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The string with the human-readable text form.
Details:
Prints the section into a human-readable text form. This is a form like gtk.css:32:1-23 to denote line 32, characters 1 to 23 in the gtk.css file.
See also:
2025-2-25
Function gtk:css-section-bytes (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The g:bytes instance with the bytes from which section was parsed.
Details:
Gets the bytes that the section was parsed from.

Since 4.16
See also:
#2025-2-25
Function gtk:css-section-file (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The namestring for the file that section was parsed from or nil if section was parsed from other data.
Details:
Gets the file that the section was parsed from. If no such file exists, for example because the CSS was loaded via the gtk:css-provider-load-from-string function, then nil is returned.
See also:
#2025-2-25
Function gtk:css-section-parent (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The gtk:css-section parent section, or nil if none.
Details:
Gets the parent section for the given section. The parent section is the section that contains this section.
See also:
#2025-2-25
Function gtk:css-section-start-location (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The gtk:css-location instance with the start location of the section.
Details:
Returns the location in the CSS document where this section starts.
See also:
2025-2-25
Function gtk:css-section-end-location (section)
Arguments:
section -- a gtk:css-section instance
Returns:
The gtk:css-location instance with the end location of the section.
Details:
Returns the location in the CSS document where this section ends.
See also:
2025-2-25

GtkCssProvider

Class gtk:css-provider
Superclasses:
gtk:style-provider, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:css-provider object is an object implementing the gtk:style-provider interface. It is able to parse CSS-like input in order to style widgets.

An application can make GTK parse a specific CSS style sheet by calling the gtk:css-provider-load-from-file or gtk:css-provider-load-from-resource functions and adding the provider with the gtk:style-context-add-provider or gtk:style-context-add-provider-for-display functions.

In addition, certain files will be read when GTK is initialized. First, the $XDG_CONFIG_HOME/gtk-4.0/gtk.css file is loaded if it exists. Then, GTK loads the first existing file among XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css, $HOME/.themes/THEME/gtk-VERSION/gtk:VARIANT.css, $XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css and DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css, where THEME is the name of the current theme, see the gtk-icon-theme-name setting setting, VARIANT is the variant to load, see the gtk-application-prefer-dark-theme setting, DATADIR is the prefix configured when GTK was compiled (unless overridden by the GTK_DATA_PREFIX environment variable), and VERSION is the GTK version number. If no file is found for the current version, GTK tries older versions all the way back to 4.0.

To track errors while loading CSS, connect to the "parsing-error" signal.
Signal Details:
The "parsing-error" signal
lambda (provider section error)    :run-last      
provider
The gtk:css-provider object that had a parsing error.
section
The gtk:css-section instance the error happened in.
error
The parsing error of type GError.
Signals that a parsing error occured. The section argument describes the actual location of the error as accurately as possible. Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal.

Note that this signal may be emitted at any time as the CSS provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called.
See also:
2025-1-11
Function gtk:css-provider-new ()
Returns:
The new gtk:css-provider object.
Details:
Returns a newly created CSS provider object.
See also:
2025-1-11
Function gtk:css-provider-load-named (provider name &optional variant)
Arguments:
provider -- a gtk:css-provider object
name -- a string for the theme name
variant -- an optional string for a variant to load, for example, a "dark" variant
Details:
Loads a theme from the usual theme paths. The actual process of finding the theme might change between releases, but it is guaranteed that this function uses the same mechanism to load the theme that GTK uses for loading its own theme.
See also:
2025-1-11
Function gtk:css-provider-load-from-bytes (provider data)
Arguments:
provider -- a gtk:css-provider object
data -- a g:bytes instance containing the CSS data to load
Details:
Loads data into the CSS provider. This clears any previously loaded information.

Since 4.12
See also:
2025-1-11
Function gtk:css-provider-load-from-data (provider data)
Arguments:
provider -- a gtk:css-provider object
data -- a string for the CSS data
Details:
Loads data into the CSS provider, making it clear any previously loaded information. To track errors while loading CSS, connect to the "parsing-error" signal of the gtk:css-provider object.
Warning:
This function is deprecated since 4.12. Use the gtk:css-provider-load-from-string or gtk:css-provider-load-from-bytes functions instead.
See also:
2025-1-11
Function gtk:css-provider-load-from-file (provider file)
Arguments:
provider -- a gtk:css-provider object
file -- a g:file object pointing to a file to load
Details:
Loads the data contained in file into the CSS provider, making it clear any previously loaded information. To track errors while loading CSS, connect to the "parsing-error" signal of the gtk:css-provider object.
See also:
2025-1-11
Function gtk:css-provider-load-from-path (provider path)
Arguments:
provider -- a gtk:css-provider object
path -- a pathname or namestring for the path of a file to load, in the GLib filename encoding
Details:
Loads the data contained in path into the CSS provider, making it clear any previously loaded information. To track errors while loading CSS, connect to the "parsing-error" signal of the gtk:css-provider object.
See also:
2025-1-11
Function gtk:css-provider-load-from-resource (provider path)
Arguments:
provider -- a gtk:css-provider object
path -- a string for the resource path
Details:
Loads the data contained in the resource at path into the CSS provider, clearing any previously loaded information. To track errors while loading CSS, connect to the "parsing-error" signal of the gtk:css-provider object.
See also:
2025-1-11
Function gtk:css-provider-load-from-string (provider str)
Arguments:
provider -- a gtk:css-provider object
str -- a string for the CSS data to load
Details:
Loads data into the CSS provider. This clears any previously loaded information.

Since 4.12
See also:
2025-1-11
Function gtk:css-provider-to-string (provider)
Arguments:
provider -- a gtk:css-provider object to write to a string
Returns:
The string representing the CSS provider.
Details:
Convertes the CSS provider into a string representation in CSS format. Using the gtk:css-provider-load-from-string function with the return value from this function on a new CSS provider created with the gtk:css-provider-new function will basically create a duplicate of this provider.
See also:
2025-2-25

GtkIconPaintable

Interface gtk:symbolic-paintable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:symbolic-paintable interface is an interface that support symbolic colors in paintables. The gdk:paintable classes implementing the interface will have the Gtk.SymbolicPaintableInterface.snapshot_symbolic virtual function called and have the colors for drawing symbolic icons passed. At least 4 colors are guaranteed to be passed every time.

These 4 colors are the foreground color, and the colors to use for errors, warnings and success information in that order. More colors may be added in the future.

Since 4.6
See also:
2023-8-30
Class gtk:icon-paintable
Superclasses:
gdk:paintable, gtk:symbolic-paintable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
file
The file property of type g-file (Read / Write / Construct only)
The file representing the icon, if any.
icon-name
The icon-name property of type :string (Read / Write / Construct only)
The icon name that was chosen during lookup.
is-symbolic
The is-symbolic property of type :boolean (Read / Write / Construct only)
Whether the icon is symbolic or not.
Returned by:
Slot Access Functions:
Details:
Contains information found when looking up an icon in a gtk:icon-theme object and supports painting it as a gdk:paintable object. The gtk:icon-paintable class implements the gdk:paintable and gtk:symbolic-paintable interfaces.
See also:
gtk:icon-theme
gdk:paintable
gtk:symbol-paintable
2023-8-30
Accessor gtk:icon-paintable-file (object)
Syntax:
(gtk:icon-paintable-file object) => file
Arguments:
object -- a gtk:icon-paintable object
file -- a g-file object for the icon, or nil
Details:
Accessor of the file slot of the gtk:icon-paintable class. The gtk:icon-paintable-file function gets the g-file object that was used to load the icon, or nil if the icon was not loaded from a file.
See also:
2023-8-30
Accessor gtk:icon-paintable-icon-name (object)
Syntax:
(gtk:icon-paintable-icon-name object) => name
Arguments:
object -- a gtk:icon-paintable object
name -- a string with the themed icon name for the icon, or nil if its not a themed icon
Details:
Accessor of the icon-name slot of the gtk:icon-paintable class. The gtk:icon-paintable-icon-name function gets the icon name being used for this icon.

When an icon looked up in the icon theme was not available, the icon theme may use fallback icons - either those specified to the gtk:icon-theme-lookup-icon function or the always-available "image-missing". The icon chosen is returned by this function.

If the icon was created without an icon theme, this function returns nil.
See also:
2023-8-30
Accessor gtk:icon-paintable-is-symbolic (object)
Syntax:
(gtk:icon-paintable-is-symbolic object) => symbolic
Arguments:
object -- a gtk:icon-paintable object
symbolic -- true if the icon is symbolic, false otherwise
Details:
Accessor of the is-symbolic slot of the gtk:icon-paintable class. The gtk:icon-paintable-is-symbolic function checks if the icon is symbolic or not. This currently uses only the file name and not the file contents for determining this. This behaviour may change in the future.

Note that to render a symbolic gtk:icon-paintable object properly, with recoloring, you have to set its icon name on a gtk:image widget.
See also:
2023-8-30
Function gtk:icon-paintable-new-for-file (file size scale)
Arguments:
file -- a g-file object
size -- an integer with the desired icon size
scale -- an integer with he desired scale
Returns:
The gtk:icon-paintable object containing the icon.
Details:
Creates a gtk:icon-paintable object for a file with a given size and scale. The icon can then be rendered by using it as a gdk:paintable object.
See also:
2024-10-9

GtkIconTheme

GFlags gtk:icon-lookup-flags
Declaration:
(gobject:define-gflags "GtkIconLookupFlags" icon-lookup-flags
  (:export t
   :type-initializer "gtk_icon_lookup_flags_get_type")
  (:none 0)
  (:force-regular  #.(ash 1 0))
  (:force-symbolic #.(ash 1 1))
  (:preload        #.(ash 1 2)))  
Values:
:none
Perform a regular lookup. Since 4.18
:force-regular
Try to always load regular icons, even when symbolic icon names are given.
:force-symbolic
Try to always load symbolic icons, even when regular icon names are given.
:preload
Starts loading the texture in the background so it is ready when later needed.
Details:
Used to specify options for the gtk:icon-theme-lookup-icon function.
See also:
2025-3-29
Class gtk:icon-theme
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
display
The display property of type gdk:display (Read / Write)
The display that the icon theme object is attached to.
icon-names
The icon-names property of type glib:strv-t (Read)
The icon names that are supported by the icon theme.
resource-path
The resource-path property of type glib:strv-t (Read / Write)
The resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as @path/16x16/actions/run.png. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback.
search-path
The search-path property of type glib:strv-t (Read / Write)
The search path for this icon theme. When looking for icons, GTK will search for a subdirectory of one or more of the directories in the search path with the same name as the icon theme containing an index.theme file. Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the home directory of the user.
theme-name
The theme-name property of type :string (Read / Write)
The name of the icon theme that is being used. Unless set to a different value, this will be the value of the gtk-icon-theme-name property of the gtk:settings object associated to the display of the icon theme object.
Default value: nil
Slot Access Functions:
Details:
The gtk:icon-theme class provides a facility for looking up icons by name and size. The main reason for using a name rather than simply providing a filename is to allow different icons to be used depending on what icon theme is selected by the user. The operation of icon themes on Linux and Unix follows the Icon Theme Specification. There is a default icon theme, named Hicolor where applications should install their icons, but more additional application themes can be installed as operating system vendors and users choose.

In many cases, named themes are used indirectly, via the gtk:image widget rather than directly, but looking up icons directly is also simple. The gtk:icon-theme object acts as a database of all the icons in the current theme. You can create new gtk:icon-theme objects, but it is much more efficient to use the standard icon theme of the gtk:widget widget so that the icon information is shared with other people looking up icons.
Examples:
In the case where the default screen is being used, looking up an icon can be as simple as:
(let* ((theme (gtk:icon-theme-for-display (gdk:display-default)))
       (paintable (gtk:icon-theme-lookup-icon theme
                                              "gtk-ok"    ; icon name
                                              nil         ; fallbacks
                                              48          ; size
                                              1           ; scale
                                              :none)))    ; no flags
   ... )    
Signal Details:
The "changed" signal
lambda (theme)    :run-last      
theme
The gtk:icon-theme object.
Emitted when the current icon theme is switched or GTK detects that a change has occurred in the contents of the current icon theme.
See also:
2025-3-29
Accessor gtk:icon-theme-display (object)
Syntax:
(gtk:icon-theme-display object) => display
(setf (gtk:icon-theme-display object) display)
Arguments:
object -- a gtk:icon-theme object
display -- a gdk:display object
Details:
Accessor of the display slot of the gtk:icon-theme class. The gtk:icon-theme-display function returns the display that the gtk:icon-theme object was created for. The (setf gtk:icon-theme-display) function sets the display.
See also:
2025-3-29
Accessor gtk:icon-theme-icon-names (object)
Syntax:
(gtk:icon-theme-icon-names object) => names
Arguments:
object -- a gtk:icon-theme object
names -- a list of strings for the icon names
Details:
Accessor of the icon-names slot of the gtk:icon-theme class. The gtk:icon-theme-icon-names function lists the names of icons in the current icon theme.
See also:
2025-3-29
Accessor gtk:icon-theme-resource-path (object)
Syntax:
(gtk:icon-theme-resource-path object) => path
(setf (gtk:icon-theme-resource-path object) path
Arguments:
object -- a gtk:icon-theme object
path -- a list of strings for the resource paths
Details:
Accessor of the resource-path slot of the gtk:icon-theme class. The gtk:icon-theme-resource-path function gets the current resource paths. The (setf gtk:icon-theme-resource-path) function sets the resource paths that will be looked at when looking for icons, similar to search paths.

The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as @path/16x16/actions/run.png or @path/scalable/actions/run.svg.

Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback, but they are treated like unthemed icons.
See also:
2025-3-29
Accessor gtk:icon-theme-search-path (object)
Syntax:
(gtk:icon-theme-search-path object) => path
(setf (gtk:icon-theme-search-path object) path
Arguments:
object -- a gtk:icon-theme object
path -- a list of strings for the search paths
Details:
Accessor of the search-path slot of the gtk:icon-theme class. The gtk:icon-theme-search-path function gets the current search path. The (setf gtk:icon-theme-search-path) function sets the search path for the icon theme object. When looking for an icon theme, GTK will search for a subdirectory of one or more of the directories in path with the same name as the icon theme containing an index.theme file. Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the home directory of the user.

In addition if an icon found is not found either in the current icon theme or the default icon theme, and an image file with the right name is found directly in one of the elements of path, then that image will be used for the icon name. This is legacy feature, and new icons should be put into the fallback icon theme, which is called hicolor, rather than directly on the icon path.
See also:
2025-3-29
Accessor gtk:icon-theme-theme-name (object)
Syntax:
(gtk:icon-theme-theme-name object) => name
(setf (gtk:icon-theme-theme-name object) name
Arguments:
object -- a gtk:icon-theme object
name -- a string for the current icon theme name
Details:
Accessor of the theme-name slot of the gtk:icon-theme class. The gtk:icon-theme-theme-name function gets the current icon theme name. The (setf gtk:icon-theme-theme-name) function sets the name of the icon theme that the gtk:icon-theme object uses overriding system configuration. This function cannot be called on the icon theme objects returned from the gtk:icon-theme-for-display function.
See also:
2025-3-29
Function gtk:icon-theme-new ()
Returns:
The newly created gtk:icon-theme object.
Details:
Creates a new icon theme object. Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you will want to use the gtk:icon-theme-for-display function rather than creating a new icon theme object for scratch.
See also:
2025-3-29
Function gtk:icon-theme-for-display (display)
Arguments:
display -- a gdk:display object
Returns:
The unique gtk:icon-theme object associated with the given display. This icon theme is associated with the display and can be used as long as the display is open.
Details:
Gets the icon theme object associated with display. If this function has not previously been called for the given display, a new icon theme object will be created and associated with the display. Icon theme objects are fairly expensive to create, so using this function is usually a better choice than calling the gtk:icon-theme-new function and setting the display yourself. By using this function a single icon theme object will be shared between users.
See also:
2025-3-29
Function gtk:icon-theme-add-search-path (theme path)
Arguments:
theme -- a gtk:icon-theme object
path -- a string for the directory name to append to the icon path
Details:
Appends a directory to the search path.
See also:
#2025-3-29
Function gtk:icon-theme-add-resource-path (theme path)
Arguments:
theme -- a gtk:icon-theme object
path -- a string for a resource path
Details:
Adds a resource path that will be looked at when looking for icons, similar to search paths. This function should be used to make application specific icons available as part of the icon theme.
See also:
#2025-3-29
Function gtk:icon-theme-has-icon (theme name)
Arguments:
theme -- a gtk:icon-theme object
name -- a string for the name of an icon
Returns:
True if the icon theme includes an icon for name.
Details:
Checks whether an icon theme includes an icon for a particular name.
See also:
2025-3-29
Function gtk:icon-theme-has-gicon (theme gicon)
Arguments:
theme -- a gtk:icon-theme object
gicon -- a g:icon object
Returns:
True if the icon theme includes an icon for gicon.
Details:
Checks whether an icon theme includes an icon for a particular g:icon object.

Since 4.2
See also:
#2025-3-29
Function gtk:icon-theme-lookup-icon (theme name fallbacks size scale direction flags)
Arguments:
theme -- a gtk:icon-theme object
name -- a string for the name of an icon
fallbacks -- a list of strings for fallback icons
size -- an integer for the desired icon size
scale -- an integer for the window scale this will be displayed on
direction -- a value of the gtk:text-direction enumeration
flags -- a value of the gtk:icon-lookup-flags flags
Returns:
The gtk:icon-paintable object containing the icon.
Details:
Looks up a named icon for a desired size and window scale, returning a gtk:icon-paintable object. The icon can then be rendered by using it as a gdk:paintable object, or you can get information such as the filename and size.

If the icon name is not available and fallbacks are provided, they will be tried in order.

If no matching icon is found, then a paintable that renders the "missing icon" icon is returned. If you need to do something else for missing icons you need to use the gtk:icon-theme-has-icon function.

Note that you probably want to listen for icon theme changes and update the icon.
See also:
2025-3-29
Function gtk:icon-theme-lookup-by-gicon (theme icon size scale direction flags)
Arguments:
theme -- a gtk:icon-theme object
icon -- a g:icon object to look up
size -- an integer for the desired icon size
scale -- an integer for the desired scale
direction -- a value of the gtk:text-direction enumeration
flags -- a value of the gtk:icon-lookup-flags flags
Returns:
The gtk:icon-paintable object containing the icon.
Details:
Looks up an icon for a desired size and window scale, returning a gtk:icon-paintable object. The icon can then be rendered by using it as a gdk:paintable object, or you can get information such as the filename and size.
See also:
#2025-3-29
Function gtk:icon-theme-icon-sizes (theme name)
Arguments:
theme -- a gtk:icon-theme object
name -- a string for the name of an icon
Returns:
The Lisp array of integer with the sizes at which the icon is available.
Details:
Returns an array of integers describing the sizes at which the icon is available without scaling. A size of -1 means that the icon is available in a scalable format.
See also:
#2025-3-29

Deprecated

Deprecated since GTK 4.10

GtkDialog

GFlags gtk:dialog-flags
Declaration:
(gobject:define-gflags "GtkDialogFlags" dialog-flags
  (:export t
   :type-initializer "gtk_dialog_flags_get_type")
  (:modal               #.(ash 1 0))
  (:destroy-with-parent #.(ash 1 1))
  (:use-header-bar      #.(ash 1 2)))  
Values:
:modal
Make the constructed dialog modal.
:destroy-with-parent
Destroy the dialog when its parent is destroyed.
:use-header-bar
Create the dialog with actions in the header bar instead of an action area.
Details:
Flags used to influence the gtk:dialog widget construction.
See also:
2025-2-26
Class gtk:dialog
Superclasses:
Documented Subclasses:
Direct Slots:
use-header-bar
The use-header-bar property of type :int (Read / Write / Construct only)
True if the dialog uses a header bar for action buttons instead of the action area. For technical reasons, this property is declared as an integer property, use the value 1 for true or -1 for false.
Allowed values: [-1, 1]
Default value: -1
Returned by:
Slot Access Functions:
Details:
Dialogs are a convenient way to prompt the user for a small amount of input. Typicall uses are to display a message, ask a question, or anything else that does not require extensive effort on the part of the user.

Figure: GtkDialog

The main area of a gtk:dialog widget is called the "content area", and is yours to populate with widgets such a gtk:label or a gtk:entry widget, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your gtk:dialog widget using the gtk:dialog-new-with-buttons function, or use the gtk:dialog-add-button, gtk:dialog-add-buttons, or gtk:dialog-add-action-widget functions.

The gtk:dialog widgets uses some heuristics to decide whether to add a Close button to the window decorations. If any of the action buttons use the :close or :cancel response ID, the Close button is omitted.

Clicking a button that was added as an action widget will emit the "response" signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs. These are entirely user-defined. But for convenience, you can use the response IDs in the gtk:response-type enumeration, these all have values less than zero. If a dialog receives a delete event, the "response" signal will be emitted with the :delete-event response ID.

Dialogs are created with a call to the gtk:dialog-new function or the gtk:dialog-new-with-buttons function. The latter is recommended. It allows you to set the dialog title, some convenient flags, and add buttons.

A "modal" dialog, that is, one which freezes the rest of the application from user input, can be created by calling the gtk:window-modal function on the dialog. When using the gtk:dialog-new-with-buttons function, you can also pass the :modal flag to make a dialog modal.
Examples:
For the simple dialog in the following example, a gtk:message-dialog widget would save some effort. But you would need to create the dialog contents manually if you had more than a simple message in the dialog.
;; Function to open a dialog to display the message provided.
(defun create-quick-message (parent msg)
  (let ((dialog (gtk:dialog-new-with-buttons "Message"
                                             parent
                                             '(:destroy-with-parent :modal)
                                             "OK"
                                             :ok)))
    (g:signal-connect dialog "response"
                      (lambda (widget response)
                        (declare (ignore response))
                        (gtk:window-destroy widget)))
    (gtk:box-append (gtk:dialog-content-area dialog)
                    (make-instance 'gtk:label
                                   :label msg
                                   :margin-top 12
                                   :margin-bottom 12
                                   :margin-start 12
                                   :margin-end 12))
    (gtk:window-present dialog)))    
GtkDialog as GtkBuildable:
The gtk:dialog implementation of the gtk:buildable interface exposes the content area as an internal children with the name content_area.

The gtk:dialog implementation supports a custom <action-widgets> element, which can contain multiple <action-widget> elements. The "response" attribute specifies a numeric response, and the content of the element is the ID of the widget, which should be a child of the action area of the dialog. To mark a response as default, set the "default" attribute of the <action-widget> element to true.

The gtk:dialog implementation supports adding action widgets by specifying "action" as the "type" attribute of a <child> element. The widget will be added either to the action area or the headerbar of the dialog, depending on the use-header-bar property. The response ID has to be associated with the action widget using the <action-widgets> element.

Example: A gtk:dialog UI definition fragment.
<object class="GtkDialog" id="dialog1">
  <child type="action">
    <object class="GtkButton" id="button_cancel"/>
  </child>
  <child type="action">
    <object class="GtkButton" id="button_ok">
      <property name="can-default">True</property>
    </object>
  </child>
  <action-widgets>
    <action-widget response="cancel">button_cancel</action-widget>
    <action-widget response="ok" default="true">button_ok</action-widget>
  </action-widgets>
</object>    
Accessibility:
The gtk:dialog implementation uses the :dialog role of the gtk:accessible-role enumeration.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
Signal Details:
The "close" signal
lambda (dialog)    :action      
dialog
The gtk:dialog widget on which the signal is emitted.
A keybinding signal which gets emitted when the user uses a keybinding to close the dialog. The default binding for this signal is the Escape key.
The "response" signal
lambda (dialog response)    :run-last      
dialog
The gtk:dialog widget on which the signal is emitted.
response
The integer with the response ID.
Emitted when an action widget is clicked. The signal is also emitted when the gtk:dialog-response function is called. On a delete event, the response ID is the :delete-event value of the gtk:response-type enumeration. Otherwise, it depends on which action widget was clicked.
See also:
2025-2-26
Accessor gtk:dialog-use-header-bar (object)
Syntax:
(gtk:dialog-use-header-bar object) => setting
(setf (gtk:dialog-use-header-bar object) setting)
Arguments:
object -- a gtk:dialog widget
setting -- true if the dialog uses a header bar
Details:
Accessor of the use-header-bar slot of the gtk:dialog class. True if the dialog uses a header bar for action buttons instead of the action area. For technical reasons, this property is declared as an integer property, use the value 1 for true or -1 for false.

Builtin gtk:dialog subclasses such as the gtk:color-chooser-dialog widget set the use-header-bar property according to platform conventions, using the gtk-dialogs-use-header setting.

Here is how you can achieve the same:
(let* ((settings (gtk:settings-default))
       (setting (g:object-property settings "gtk-dialogs-use-header"))
       (dialog (make-instance 'gtk:dialog
                              :use-header-bar setting)))
  ... )  
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
2025-2-26
Function gtk:dialog-new ()
Returns:
The new gtk:dialog widget.
Details:
Creates a new dialog. Widgets should not be packed into the dialog directly, but into the content area, which can be accessed with the gtk:dialog-content-area function.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
2025-2-26
Function gtk:dialog-new-with-buttons (title parent flags &rest buttons)
Arguments:
title -- a string for the title of the dialog, or nil
parent -- a gtk:window transient parent for the dialog, or nil
flags -- a gtk:dialog-flags value for the flags of the dialog
buttons -- pairs with a button text and the response ID for the button, which is a positive integer or a value of the gtk:response-type enumeration
Returns:
The new gtk:dialog widget.
Details:
Creates a new dialog with title title, or nil for the default title, and transient parent parent, or nil for none. The flags argument can be used to make the dialog modal with the :modal flag of the gtk:dialog-flags flags and/or to have it destroyed along with its transient parent with the :destroy-with-parent flag.

After the flags argument, button text/response ID pairs should be listed. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the gtk:response-type enumeration. If the user clicks one of these dialog buttons, the gtk:dialog widget will emit the "response" signal with the corresponding response ID. If a gtk:dialog widget receives the "delete-event" signal, it will emit the "response" signal with a :delete-event response ID. However, destroying a dialog does not emit the "response" signal. So be careful relying on the "response" signal when using the :destroy-with-parent flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog.
Examples:
(let ((dialog (gtk:dialog-new-with-buttons "My dialog"
                                           main-app-window
                                           '(:modal :destroy-with-parent)
                                           "_OK"
                                           :accept
                                           "_Cancel"
                                           :reject)))
  ... )    
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
2025-2-26
Function gtk:dialog-response (dialog response)
Arguments:
dialog -- a gtk:dialog widget
response -- a response ID, which is a positive integer or a value of the gtk:response-type enumeration
Details:
Emits the "response" signal with the given response ID. Used to indicate that the user has responded to the dialog in some way.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-add-button (dialog text response)
Arguments:
dialog -- a gtk:dialog widget
text -- a string for the text of the button
response -- response ID for the button, which is a positive integer or a value of the gtk:response-type enumeration
Returns:
The gtk:button widget that was added.
Details:
Adds a button with the given text and sets things up so that clicking the button will emit the "response" signal with the given response value. The button is appended to the end of the action area of the dialog.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-add-buttons (dialog &rest buttons)
Arguments:
dialog -- a gtk:dialog widget
buttons -- pairs with a button text and the response ID, which is a positive integer or a value of the gtk:response-type enumeration
Details:
Adds more buttons, same as calling the gtk:dialog-add-button function repeatedly. Each button must have both text and response ID.
Notes:
The Lisp implementation does not call the C function, but the gtk:dialog-add-button function is called in a loop to add the buttons.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-add-action-widget (dialog child response)
Arguments:
dialog -- a gtk:dialog widget
child -- an activatable gtk:widget object
response -- response ID for child, which is a positive integer or a value of the gtk:response-type enumeration
Details:
Adds an activatable child widget to the action area of the dialog, connecting a signal handler that will emit the "response" signal on the dialog when the child widget is activated. The child widget is appended to the end of the action area of the dialog. If you want to add a non-activatable widget, simply pack it into the action area of the dialog.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-set-default-response (dialog response)
Arguments:
dialog -- a gtk:dialog widget
response -- a response ID, which is a positive integer or a value of the gtk:response-type enumeration
Details:
Sets the last widget in the action area of the dialog with the given response value as the default widget for the dialog. Pressing the Enter key normally activates the default widget.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-set-response-sensitive (dialog response setting)
Arguments:
dialog -- a gtk:dialog widget
response -- a response ID, which is a positive integer or a value of the gtk:response-type enumeration
setting -- true for sensitive
Details:
Calls the gtk:widget-sensitive function for each widget in the action area of the dialog with the given response value. This is a convenient way to sensitize/desensitize dialog buttons.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-response-for-widget (dialog widget)
Arguments:
dialog -- a gtk:dialog widget
widget -- a gtk:widget object in the action area of dialog
Returns:
The response ID of widget, which is a positive integer or a value of the gtk:response-type enumeration, the value is :none if widget does not have a response ID set.
Details:
Gets the response ID of the widget in the action area of the dialog.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-widget-for-response (dialog response)
Arguments:
dialog -- a gtk:dialog widget
response -- a response ID, which is a positive integer or a value of the gtk:response-type enumeration
Returns:
The gtk:widget button that uses the given response value, or nil.
Details:
Gets the button that uses the given response ID in the action area of the dialog.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-content-area (dialog)
Arguments:
dialog -- a gtk:dialog widget
Returns:
The vertical gtk:box widget with the content area.
Details:
Returns the content area of the dialog.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26
Function gtk:dialog-header-bar (dialog)
Arguments:
dialog -- a gtk:dialog widget
Returns:
The gtk:header-bar widget.
Details:
Returns the header bar of the dialog. Note that the header bar is only used by the dialog if the use-header-bar property is true.
Warning:
The gtk:dialog implementation is deprecated since 4.10. Use the gtk:window widget instead.
See also:
#2025-2-26

GtkMessageDialog

GEnum gtk:buttons-type
Declaration:
(gobject:define-genum "GtkButtonsType" buttons-type
  (:export t
   :type-initializer "gtk_buttons_type_get_type")
  (:none 0)
  (:ok 1)
  (:close 2)
  (:cancel 3)
  (:yes-no 4)
  (:ok-cancel 5))  
Values:
:none
No buttons at all.
:ok
An OK button.
:close
A Close button.
:cancel
A Cancel button.
:yes-no
Yes and No buttons.
:ok-cancel
OK and Cancel buttons.
Details:
Prebuilt sets of buttons for the dialog. If none of these choices are appropriate, simply use the :none value and call the gtk:dialog-add-buttons function to add your own buttons.

Please note that the :ok, :yes-no and :ok-cancel values are discouraged by the GNOME Human Interface Guidelines.
See also:
2025-2-26
Class gtk:message-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
buttons
The buttons property of type gtk:buttons-type (Construct Only)
The buttons shown in the message dialog.
Note: The property can be set only in a constructor and is not readable or writable. There is no accessor.
Default value: :none
message-area
The message-area property of type gtk:widget (Read)
The gtk:box widget with :vertical orientation that corresponds to the message area of the message dialog. See the gtk:message-dialog-message-area function for a detailed description of the message area.
message-type
The message-type property of type gtk:message-type (Read / Write / Construct)
The type of the message dialog.
Default value: :info
secondary-text
The secondary-text property of type :string (Read / Write)
The secondary text for the message dialog.
Default value: nil
secondary-use-markup
The secondary-use-markup property of type :boolean (Read / Write)
True if the secondary text of the message dialog includes Pango markup.
Default value: false
text
The text property of type :string (Read / Write)
The primary text for the message dialog. If the message dialog has a secondary text, this will appear as the title.
Default value: ""
use-markup
The use-markup property of type :boolean (Read / Write)
True if the primary text for the message dialog includes Pango markup.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:message-dialog widget presents a dialog with some message text. It is simply a convenience widget. You could construct the equivalent of a message dialog from a gtk:dialog widget without too much effort, but the gtk:message-dialog widget saves typing.

Figure: GtkMessageDialog

The easiest way to do a modal message dialog is to use the :modal flag of the gtk:dialog-flags flags. The message dialog will prevent interaction with the parent window until it is hidden or destroyed. You can use the "response" signal to know when the user dismissed the message dialog.
Examples:
An example for creating a modal message dialog.
(defun create-message-dialog-simple (parent)
  (let ((dialog (make-instance 'gtk:message-dialog
                               :transient-for parent
                               :modal t
                               :message-type :info
                               :buttons :ok
                               :text "Message Dialog"
                               :secondary-text "The secondary text.")))
    ;; Handler for the "response" signal of the dialog
    (g:signal-connect dialog "response"
                      (lambda (dialog response)
                        (gtk:window-destroy dialog)))
    (gtk:window-present dialog)))    
This is a variant that uses the gtk:message-dialog-new function. The first example is more lispy and the implementation more favorable.
(defun create-message-dialog-simple2 (parent)
  (let ((dialog (gtk:message-dialog-new parent
                                        '(:modal)
                                        :info
                                        :ok-cancel
                                        "Message Dialog"
                                        parent)))
    ;; Set secondary text with the accessor
    (setf (gtk:message-dialog-secondary-text dialog)
          "Created with constructor and with two buttons.")
    ;; Handler for the "response" signal of the dialog
    (g:signal-connect dialog "response"
                      (lambda (dialog response)
                        (gtk:window-destroy dialog)))
    (gtk:window-present dialog)))    
GtkMessageDialog as GtkBuildable:
The gtk:message-dialog implementation of the gtk:buildable interface exposes the message area as an internal child with the name message_area.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-message-area (object)
Syntax:
(gtk:message-dialog-message-area object) => area
Arguments:
dialog -- a gtk:message-dialog widget
area -- a gtk:box widget with :vertical orientation
Details:
Accessor of the message-area slot of the gtk:message-dialog class. The gtk:message-dialog-message-area function returns the gtk:box widget with :vertical orientation corresponding to the "message area" in the message dialog. This is the box where the primary and secondary labels of the message dialog are packed.

You can add your own extra content to that box and it will appear below those labels. See the gtk:dialog-content-area function for the corresponding function in the parent gtk:dialog class.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-message-type (object)
Syntax:
(gtk:message-dialog-message-type object) => type
Arguments:
object -- a gtk:message-dialog widget
type -- a value of the gtk:message-type enumeration
Details:
Accessor of the message-type slot of the gtk:message-dialog class. The type of the message.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-secondary-text (object)
Syntax:
(gtk:message-dialog-secondary-text object) => text
(setf (gtk:message-dialog-secondary-text object) text)
Arguments:
object -- a gtk:message-dialog widget
text -- a string for the secondary text of the message dialog
Details:
Accessor of the secondary-text slot of the gtk:message-dialog class. The secondary text for the message dialog.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-secondary-use-markup (object)
Syntax:
(gtk:message-dialog-secondary-use-markup object) => setting
(setf (gtk:message-dialog-secondary-use-markup object) setting)
Arguments:
object -- a gtk:message-dialog widget
setting -- a boolean whether to use Pango markup
Details:
Accessor of the secondary-use-markup slot of the gtk:message-dialog class. True if the secondary text for the message dialog includes Pango markup.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-text (object)
Syntax:
(gtk:message-dialog-text object) => text
(setf (gtk:message-dialog-text object) text)
Arguments:
object -- a gtk:message-dialog widget
text -- a string for the primary text of the message dialog
Details:
Accessor of the text slot of the gtk:message-dialog class. The primary text for the message dialog. If the message dialog has a secondary text, this will appear as the title.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Accessor gtk:message-dialog-use-markup (object)
Syntax:
(gtk:message-dialog-use-markup object) => setting
(setf (gtk:message-dialog-use-markup object) setting)
Arguments:
object -- a gtk:message-dialog widget
setting -- a boolean whether to use Pango markup
Details:
Accessor of the use-markup slot of the gtk:message-dialog class. True if the primary text for the message dialog includes Pango markup.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Function gtk:message-dialog-new (parent flags type buttons message &rest args)
Arguments:
parent -- a transient gtk:window parent, or nil for none
flags -- a gtk:dialog-flags value for the flags to use
type -- a gtk:message-type value for the type of message
buttons -- a gtk:buttons-type value for the buttons to use
message -- a Lisp format string, or nil
args -- arguments for message
Returns:
The new gtk:message-dialog widget.
Details:
Creates a new message dialog, which is a simple dialog with some text the user may want to see. When the user clicks a button a "response" signal is emitted with response IDs from the gtk:response-type enumeration. See the gtk:dialog documentation for more details.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Function gtk:message-dialog-new-with-markup (parent flags type buttons message &rest args)
Arguments:
parent -- a transient gtk:window parent, or nil for none
flags -- a gtk:dialog-flags value for the flags to use
type -- a gtk:message-type value for the type of message
buttons -- a gtk:buttons-type value for the buttons to use
message -- a Lisp format string, or nil
args -- arguments for message
Returns:
The new gtk:message-dialog widget.
Details:
Creates a new message dialog, which is a simple dialog with some text which is marked up with the Pango text markup language. When the user clicks a button a "response" signal is emitted with response IDs from the gtk:response-type enumeration. See the gtk:dialog documentation for more details.

Special XML characters in the message arguments passed to this function will automatically be escaped as necessary. Usually this is what you want, but if you have an existing Pango markup string that you want to use literally as the label, then you need to use the gtk:message-dialog-set-markup function instead, since you cannot pass the markup string either as the format, it might contain '%' characters, or as a string argument.
Examples:
(defun create-message-dialog-new-with-markup (parent filename)
  (let ((dialog (gtk:message-dialog-new-with-markup
                                        parent
                                        '(:modal :destroy-with-parent)
                                        :error
                                        :close
                                        "<b>Error loading file ~s</b>"
                                        filename)))
    (g:signal-connect dialog "response"
                      (lambda (dialog response)
                        (declare (ignore response))
                        (gtk:window-destroy dialog)))
    (gtk:window-present dialog)))    
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Function gtk:message-dialog-set-markup (dialog text)
Arguments:
dialog -- a gtk:message-dialog widget
text -- a markup string, see Pango markup format
Details:
Sets the text for the message dialog to be text, which is marked up with the Pango text markup language.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Function gtk:message-dialog-format-secondary-text (dialog message &rest args)
Arguments:
dialog -- a gtk:message-dialog widget
message -- a Lisp format string, or nil
args -- arguments for message
Details:
Sets the secondary text for the message dialog to be message with the arguments in args. Note that setting a secondary text makes the primary text become bold, unless you have provided explicit markup.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26
Function gtk:message-dialog-format-secondary-markup (dialog message &rest args)
Arguments:
dialog -- a gtk:message-dialog widget
message -- a Lisp format string with markup, see Pango markup format, or nil
args -- arguments for message
Details:
Sets the secondary text for the message dialog to be message with the arguments in args, which is marked up with the Pango text markup language. Note that setting a secondary text makes the primary text become bold, unless you have provided explicit markup. Due to an oversight in the C implementation, this function does not escape special XML characters like the gtk:message-dialog-new-with-markup function does.
Warning:
The gtk:message-dialog widget is deprecated since 4.10. Use the gtk:alert-dialog widget instead.
See also:
2025-2-26

GtkAssistant

GEnum gtk:assistant-page-type
Declaration:
(gobject:define-genum "GtkAssistantPageType" assistant-page-type
  (:export t
   :type-initializer "gtk_assistant_page_type_get_type")
  (:content  0)
  (:intro    1)
  (:confirm  2)
  (:summary  3)
  (:progress 4)
  (:custom   5))  
Values:
:content
The page has regular contents. Both the Back and Forward buttons will be shown.
:intro
The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a Next page.
:confirm
The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown.
:summary
The page informs the user of the changes done. Only the Close button will be shown.
:progress
Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete. Only the Back button will be shown.
:custom
Used for when other page types are not appropriate. No buttons will be shown, and the application must add its own buttons through the gtk:assistant-add-action-widget function.
Details:
An enumeration for determining the page role inside the gtk:assistant widget. It is used to handle buttons sensitivity and visibility.

Note that an assistant needs to end its page flow with a page of :confirm, :summary or :progress type to be correct. The Cancel button will only be shown if the page is not "committed". See the gtk:assistant-commit function for details.
See also:
2025-2-27
Class gtk:assistant-page
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child
The child property of type gtk:widget (Read / Write / Construct only)
The content of the assistant page.
complete
The complete property of type :boolean (Read / Write)
Setting this property to true marks a page as complete, that is, all the required fields are filled out. GTK uses this information to control the sensitivity of the navigation buttons.
Default value: false
page-type
The page-type property of type gtk:assistant-page-type (Read / Write)
The type of the assistant page.
Default value: :content
title
The title property of type :string (Read / Write)
The title of the page.
Default value: nil
Slot Access Functions:
Details:
The gtk:assistant-page object is an auxiliary object used by the gtk:assistant class.
Notes:
The accessor functions for the complete, page-type, and title properties are not exported for use. The values of the properties are accessed with the gtk:assistant-page-complete, gtk:assistant-page-type, and gtk:assistant-page-title functions, which are defined for the gtk:assistant widget.
Warning:
The gtk:assistant-page implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Accessor gtk:assistant-page-child (object)
Syntax:
(gtk:assistant-page-child object) => page
Arguments:
object -- a gtk:assistant-page object
page -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:assistant-page class. The gtk:assistant-page-child function returns the child widget to which the page belongs.
Warning:
The gtk:assistant-page implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Class gtk:assistant
Superclasses:
Documented Subclasses:
None
Direct Slots:
pages
The pages property of type g:list-model (Read)
The pages of the assistant.
use-header-bar
The use-header-bar property of type :int (Read / Write / Construct)
True if the assistant uses a header bar for action buttons instead of the action area. For technical reasons, this property is declared as an integer property, use the value 1 for true or -1 for false.
Allowed values: [-1, 1]
Default value: -1
Returned by:
Slot Access Functions:
Details:
The gtk:assistant widget is used to represent a generally complex operation splitted in several steps. Each step consists of one or more pages. The assitant guides the user through the pages, and controls the page flow to collect the data needed for the operation.

Figure: GtkAssistant

The gtk:assistant widget handles which buttons to show and to make sensitive based on page sequence knowledge and the type of each page in addition to state information like the completion and committed page statuses.

If you have a case that does not quite fit in the gtk:assistant widgets way of handling buttons, you can use the :custom value of the gtk:assistant-page-type enumeration and handle buttons yourself.

The gtk:assistant widget maintains a gtk:assistant-page object for each added child, which holds additional per-child properties. You obtain the gtk:assistant-page object for the child widget with the gtk:assistant-page function.
GtkAssistant as GtkBuildable:
The gtk:assistant implementation of the gtk:buildable interface exposes the action area as internal children with the name "action_area". To add pages to an assistant in the gtk:builder object, simply add it as a child widget to the assistant. If you need to set per-object properties, create a gtk:assistant-page object explicitly, and set the child widget as a property on it.
CSS nodes:
The gtk:assistant implementation has a single CSS node with the name window and .assistant style class.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
Signal Details:
The "apply" signal
lambda (assistant)    :run-last      
assistant
The gtk:assistant widget which received the signal.
The signal is emitted when the Apply button is clicked. The default behavior of the assistant is to switch to the page after the current page, unless the current page is the last one. A handler for the "apply" signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a :progress page after the :confirm page and handle this operation within the "prepare" signal of the progress page.
The "cancel" signal
lambda (assistant)    :run-last      
assistant
The gtk:assistant widget which received the signal.
The signal is emitted when the Cancel button is clicked.
The "close" signal
lambda (assistant)    :run-last      
assistant
The gtk:assistant widget which received the signal.
The signal is emitted either when the Close button of a summary page is clicked, or when the Apply button in the last page in the flow is clicked, which is the :confirm page.
The "escape" signal
lambda (assistant)    :action      
assistant
The gtk:assistant widget which received the signal.
The action signal for the Escape binding.
The "prepare" signal
lambda (assistant page)    :run-last      
assistant
The gtk:assistant widget which received the signal.
page
The gtk:widget object for the current page.
The signal is emitted when a new page is set as the assistants current page, before making the new page visible. A handler for this signal can do any preparations which are necessary before showing the page.
See also:
2025-2-27
Accessor gtk:assistant-pages (object)
Syntax:
(gtk:assistant-pages object) => pages
(setf (gtk:assistant-pages object) pages)
Arguments:
object -- a gtk:assistant widget
pages -- a g:list-model object with the pages
Details:
Accessor of the pages slot of the gtk:assistant class. The gtk:assistant-pages function gets a list model with the assistant pages.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Accessor gtk:assistant-use-header-bar (object)
Syntax:
(gtk:assistant-use-header-bar object) => setting
(setf (gtk:assistant-use-header-bar object) setting)
Arguments:
object -- a gtk:assistant widget
setting -- true if the assistant uses a header bar
Details:
Accessor of the use-header-bar slot of the gtk:assistant class. True if the assistant uses a header bar for action buttons instead of the action area. For technical reasons, this property is declared as an integer property, use the value 1 for true or -1 for false.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-new ()
Returns:
The gtk:assistant widget.
Details:
Creates a new assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-page (assistant child)
Arguments:
assistant -- a gtk:assistant widget
child -- a gtk:widget child widget
Details:
Returns the gtk:assistant-page object for the child widget.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-current-page (assistant)
Syntax:
(gtk:assistant-current-page assistant) => index
(setf (gtk:assistant-current-page assistant) index)
Arguments:
assistant -- a gtk:assistant widget
index -- an integer for the index of the page to switch to, starting from 0, if negative, the last page will be used, if greater than the number of pages in the assistant, nothing will be done
Details:
The gtk:assistant-current-page function returns the page number of the current page in the assistant. The (setf gtk:assistant-current-page) function switches the page in the assistant to index. Note that this will only be necessary in custom buttons, as the assistant flow can be set with the gtk:assistant-set-forward-page-func function.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-n-pages (assistant)
Arguments:
assistant -- a gtk:assistant widget
Returns:
The integer with the number of pages in assistant.
Details:
Returns the number of pages in the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-nth-page (assistant index)
Arguments:
assistant -- a gtk:assistant widget
index -- an integer for the index of a page in assistant, or -1 to get the last page
Returns:
The gtk:widget child widget, or nil if the index argument is out of bounds.
Details:
Returns the child widget contained in the assistant with the given page index.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-prepend-page (assistant page)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of the assistant
Returns:
The integer with the index starting at 0 of the inserted page.
Details:
Prepends a page to the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-append-page (assistant page)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of the assistant
Returns:
The integer with the index starting at 0 of the inserted page.
Details:
Appends a page to the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-insert-page (assistant page position)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of the assistant
position -- an integer with the index starting at 0 at which to insert page, or -1 to append page to the assistant
Returns:
The index starting from 0 of the inserted page.
Details:
Inserts a page in the assistant at a given position.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-remove-page (assistant index)
Arguments:
assistant -- a gtk:assistant widget
index -- an integer for the index of a page in the assistant, or -1 to remove the last page
Details:
Removes the page with the given page index from the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Callback gtk:assistant-page-func
Syntax:
lambda (page) => result
Arguments:
page -- an integer for the page number used to calculate the Next page
result -- an integer for the next page number
Details:
A callback function used by the gtk:assistant-set-forward-page-func function to know which is the Next page given a current one. It is called both for computing the Next page when the user presses the Forward button and for handling the behavior of the Last button.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-set-forward-page-func (assistant func)
Arguments:
assistant -- a gtk:assistant widget
func -- a gtk:assistant-page-func page forwarding callback function, or nil to use the default one
Details:
Sets the page forwarding function to be func. This function will be used to determine what will be the Next page when the user presses the Forward button. Setting func to nil will make the assistant to use the default forward function, which just goes to the Next visible page.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-page-type (assistant page)
Syntax:
(gtk:assistant-page-type assistant page) => ptype
(setf (gtk:assistant-page-type assistant page) ptype)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of assistant
ptype -- a value of the gtk:assistant-page-type enumeration
Details:
The page type determines the page behavior in the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-page-title (assistant page)
Syntax:
(gtk:assistant-page-title assistant page) => title
(setf (gtk:assistant-page-title assistant page) title)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of assistant
title -- a string for the new title for page
Details:
The gtk:assistant-page-title function gets the title for the page in the assistant. The (setf gtk:assistant-page-title) function sets a title. The title is displayed in the header area of the assistant when the page is the current page.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-page-complete (assistant page)
Syntax:
(gtk:assistant-page-complete assistant page) => complete
(setf (gtk:assistant-page-complete assistant page) complete)
Arguments:
assistant -- a gtk:assistant widget
page -- a gtk:widget page of assistant
complete -- a boolean for the completeness status of the page
Details:
The gtk:assistant-page-complete function gets whether the page is complete. The (setf gtk:assistant-page-complete) function sets whether the page contents are complete. This will make the assistant update the buttons state to be able to continue the task.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-add-action-widget (assistant child)
Arguments:
assistant -- a gtk:assistant widget
child -- a gtk:widget child widget
Details:
Adds a child widget to the action area of the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-remove-action-widget (assistant child)
Arguments:
assistant -- a gtk:assistant widget
child -- a gtk:widget child widget
Details:
Removes a child widget from the action area of the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-update-buttons-state (assistant)
Arguments:
assistant -- a gtk:assistant widget
Details:
Forces the assistant to recompute the buttons state. GTK automatically takes care of this in most situations, for example, when the user goes to a different page, or when the visibility or completeness of a page changes. One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-commit (assistant)
Arguments:
assistant -- a gtk:assistant widget
Details:
Erases the visited page history so the Back button is not shown on the current page, and removes the Cancel button from subsequent pages. Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long running, unreversible operation after the user has clicked the Apply button on a confirmation page.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-2-27
Function gtk:assistant-next-page (assistant)
Arguments:
assistant -- a gtk:assistant widget
Details:
Navigate to the Next page. It is a programming error to call this function when there is no Next page. This function is for use when creating pages with the :custom value of the gtk:assistant-page-type enumeration.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27
Function gtk:assistant-previous-page (assistant)
Arguments:
assistant -- a gtk:assistant widget
Details:
Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. This function is for use when creating pages with the :custom value of the gtk:assistant-page-type enumeration.
Warning:
The gtk:assistant implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-2-27

GtkInfoBar

Class gtk:info-bar
Superclasses:
Documented Subclasses:
None
Direct Slots:
message-type
The message-type property of type gtk:message-type (Read / Write / Construct)
The type of the message. The type may be used to determine the appearance of the info bar.
Default value: :info
revealed
The revealed property of type :boolean (Read / Write)
Controls whether the action bar shows its contents or not.
Default value: true
show-close-button
The show-close-button property of type :boolean (Read / Write / Construct)
Whether to include a standard Close button.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:info-bar widget can be used to show messages to the user without showing a dialog. It is often temporarily shown at the top or bottom of a document. In contrast to the gtk:dialog widget, which has a horizontal action area at the bottom, the info bar has a vertical action area at the side.

Figure: GtkInfoBar

The API of the gtk:info-bar widget is very similar to the gtk:dialog widget, allowing you to add buttons to the action area with the gtk:info-bar-add-button or gtk:info-bar-new-with-buttons functions. The sensitivity of action widgets can be controlled with the gtk:info-bar-set-response-sensitive function. To add widgets to the main content area of an info bar, use the gtk:info-bar-add-child function.

Similar to the gtk:message-dialog widget, the contents of an info bar can by classified as error message, warning, informational message, and so on, by using the gtk:info-bar-message-type function. GTK may use the message type to determine how the message is displayed.
Examples:
Simple info bar usage.
(defun create-info-bar (msg type)
  (let ((infobar (make-instance 'gtk:info-bar
                                :message-type type
                                :show-close-button t))
        (message (make-instance 'gtk:label :label msg)))
    ;; Add a label with the message to the content of the info bar
    (gtk:info-bar-add-child infobar message)
    ;; Connect a signal handler to the info bar
    (g:signal-connect infobar "response"
                      (lambda (widget response)
                        (declare (ignore response))
                        (gtk:widget-hide widget)))
    infobar))    
GtkInfoBar as GtkBuildable:
The gtk:info-bar implementation of the gtk:buildable interface exposes the content area and action area as internal children with the names content_area and action_area.

The gtk:info-bar implementation supports a custom <action-widgets> element, which can contain multiple <action-widget> elements. The response attribute specifies a numeric response, and the content of the element is the ID of the widget, which should be a child of the dialogs action area.
CSS nodes:
The gtk:info-bar implementation has a single CSS node with name infobar. The node may get one of the .info, .warning, .error or .question style classes, depending on the message type. If the info bar shows a Close button, that button will have the .close style class applied.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code. There is no replacement in GTK for an "info bar" widget. You can use the gtk:revealer widget with a gtk:box widget containing a gtk:label widget and an optional gtk:button widget, according to your design of the application.
Signal Details:
The "close" signal
lambda (infobar)    :action      
infobar
The gtk:info-bar widget on which the signal is emitted.
The signal is a keybinding signal which gets emitted when the user uses a keybinding to dismiss the info bar. The default binding for this signal is the Escape key.
The "response" signal
lambda (infobar response)    :run-last      
infobar
The gtk:info-bar widget on which the signal is emitted.
response
The integer with the response ID.
Emitted when an action widget is clicked or the application programmer calls the gtk:dialog-response function. The response argument depends on which action widget was clicked.
See also:
2025-3-13
Accessor gtk:info-bar-message-type (object)
Syntax:
(gtk:info-bar-message-type object) => message-type
(setf (gtk:info-bar-message-type object) message-type)
Arguments:
object -- a gtk:info-bar widget
message-type -- a value of the gtk:message-type enumeration
Details:
Accessor of the message-type slot of the gtk:info-bar class. The gtk:info-bar-message-type function returns the message type of the message area. The (setf gtk:info-bar-message-type) function sets the message type. GTK uses the message type to determine how the message is displayed.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
2025-3-13
Accessor gtk:info-bar-revealed (object)
Syntax:
(gtk:info-bar-revealed object) => revealed
(setf (gtk:info-bar-revealed object) revealed)
Arguments:
object -- a gtk:info-bar widget
revealed -- a boolean whether the action bar shows its contents
Details:
Accessor of the revealed slot of the gtk:info-bar class. The gtk:info-bar-revealed function returns whether the info bar is currently revealed. The (setf gtk:info-bar-revealed) function sets the property.

Changing this will make the info bar reveal or conceal itself by means of a sliding transition. Note: this does not show or hide the info bar in the visible sense, so revealing has no effect if the visible property is false.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
2025-3-13
Accessor gtk:info-bar-show-close-button (object)
Syntax:
(gtk:info-bar-show-close-button object) => setting
(setf (gtk:info-bar-show-close-button object) setting)
Arguments:
object -- a gtk:info-bar widget
setting -- true to include a Close button
Details:
Accessor of the show-close-button slot of the gtk:info-bar class. The gtk:info-bar-show-close-button function returns whether the widget will display a standard Close button. If true, a standard Close button is shown. When clicked it emits the :close response.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
2025-3-13
Function gtk:info-bar-new ()
Returns:
The new gtk:info-bar widget.
Details:
Creates a new info bar.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
2025-3-13
Function gtk:info-bar-new-with-buttons (&rest args)
Arguments:
args -- first a string for the text and second an integer for the response ID for each button, then more pairs for each button
Returns:
The new gtk:info-bar widget.
Details:
Creates a new info bar with buttons. Button text/response ID pairs should be listed. Button text can be some arbitrary text. A response ID can be any positive number, or one of the values in the gtk:response-type enumeration. If the user clicks one of these dialog buttons, the info bar will emit the "response" signal with the corresponding response ID.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
2025-3-13
Function gtk:info-bar-add-action-widget (infobar child response)
Arguments:
infobar -- a gtk:info-bar widget
child -- an activatable gtk:widget child widget
response -- an integer for the response ID for child
Details:
Add an activatable widget to the action area of an info bar, connecting a signal handler that will emit the "response" signal on the message area when the widget is activated. The widget is appended to the end of the action area of the infor bar.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-remove-action-widget (infobar widget)
Arguments:
infobar -- a gtk:info-bar widget
widget -- a gtk:widget action widget to remove
Details:
Removes a widget from the action area of the info bar, after it been put there by a call to the gtk:info-bar-add-action-widget or gtk:info-bar-add-button function.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-add-button (infobar text response)
Arguments:
infobar -- a gtk:info-bar widget
text -- a string for the text of the button
response -- an integer for the response ID of the button
Returns:
The gtk:button widget that was added.
Details:
Adds a button with the given text, and sets things up so that clicking the button will emit the "response" signal with the given response ID. The button is appended to the end of the action area of the info bar. The button widget is returned, but usually you do not need it.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-add-buttons (infobar &rest args)
Arguments:
infobar -- a gtk:info-bar widget
args -- first a string for a button text and second an integer for a response ID, then more pairs for each button
Details:
Adds more buttons, same as calling the gtk:info-bar-add-button function repeatedly. Each button must have both text and a response ID.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-set-response-sensitive (infobar response setting)
Arguments:
infobar -- a gtk:info-bar widget
response -- an integer for a response ID
setting -- true for sensitive
Details:
Calls the gtk:widget-sensitive function for each widget in the action area of the info bar with the given response ID. A convenient way to sensitize/desensitize dialog buttons.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-set-default-response (infobar response)
Arguments:
infobar -- a gtk:info-bar widget
response -- an integer for a response ID
Details:
Sets the last widget in the action area of the info bar with the given response ID as the default widget for the info bar. Pressing the Enter key usually activates the default widget.

Note that this function currently requires the info bar to be added to a widget hierarchy.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-response (infobar response)
Arguments:
infobar -- a gtk:info-bar widget
response -- an integer for a response ID
Details:
Emits the "response" signal with the given response ID.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-add-child (infobar widget)
Arguments:
infobar -- a gtk:info-bar widget
widget -- a gtk:widget child widget to be added
Details:
Adds a widget to the content area of the info bar.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13
Function gtk:info-bar-remove-child (infobar widget)
Arguments:
infobar -- a gtk:info-bar widget
widget -- a gtk:widget child widget to be removed
Details:
Removes a widget from the content area of the info bar, after it has been added with the gtk:info-bar-add-child function.
Warning:
The gtk:info-bar implementation is deprecated since 4.10. Do not use it in newly written code.
See also:
#2025-3-13

GtkStatusbar

Class gtk:statusbar
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:statusbar widget is usually placed along the bottom of the main gtk:window widget of the application. It may provide a regular commentary of the status of the application as is usually the case in a web browser, for example, or may be used to simply output a message when the status changes, when an upload is complete in an FTP client, for example.

Figure: GtkStatusbar

Statusbars in GTK maintain a stack of messages. The message at the top of the stack of the statusbar is the one that will currently be displayed.

Any messages added to the stack of the statusbar must specify a context ID that is used to uniquely identify the source of a message. This context ID can be generated by the gtk:statusbar-context-id function, given a message and the statusbar that it will be added to. Note that messages are stored in a stack, and when choosing which message to display, the stack structure is adhered to, regardless of the context identifier of a message.

One could say that a statusbar maintains one stack of messages for display purposes, but allows multiple message producers to maintain sub-stacks of the messages they produced (via context IDs).

Statusbars are created using the gtk:statusbar-new function. Messages are added to the stack of the statusbar with the gtk:statusbar-push function. The message at the top of the stack can be removed using the gtk:statusbar-pop function. A message can be removed from anywhere in the stack if its message ID was recorded at the time it was added. This is done using the gtk:statusbar-remove function.
CSS node:
The gtk:statusbar implementation has a single CSS node with name statusbar.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
Signal Details:
The "text-popped" signal
lambda (statusbar context text)    :run-last      
statusbar
The gtk:statusbar widget which received the signal.
context
The unsigned integer with the context ID of the relevant message/statusbar.
text
The string with the message that was just popped.
Is emitted whenever a new message is popped off the stack of the status bar.
The "text-pushed" signal
lambda (statusbar context text)    :run-last      
statusbar
The gtk:statusbar widget which received the signal.
context
The unsigned integer with the context ID of the relevant message/statusbar.
text
The string with the message that was pushed.
Is emitted whenever a new message gets pushed onto the stack of the status bar.
2025-3-13
Function gtk:statusbar-new ()
Returns:
The new gtk:statusbar widget.
Details:
Creates a new statusbar ready for messages.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-3-13
Function gtk:statusbar-context-id (statusbar context)
Arguments:
statusbar -- a gtk:statusbar widget
context -- a string for the textual description of what context the new message is being used in
Returns:
The integer with the context ID.
Details:
Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-3-13
Function gtk:statusbar-push (statusbar context text)
Arguments:
statusbar -- a gtk:statusbar widget
context -- an unsigned integer for the context ID of the message, as returned by the gtk:statusbar-context-id function
text -- a string for the message to add to statusbar
Returns:
The unsigned integer with a message ID that can be used with the gtk:statusbar-remove function.
Details:
Pushes a new message onto the stack of the statusbar.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-3-13
Function gtk:statusbar-pop (statusbar context)
Arguments:
statusbar -- a gtk:statusbar widget
context -- an unsigned integer for a context identifier
Details:
Removes the first message in the stack of the statusbar with the given context ID. Note that this may not change the displayed message, if the message at the top of the stack has a different context ID.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
2025-3-13
Function gtk:statusbar-remove (statusbar context message)
Arguments:
statusbar -- a gtk:statusbar widget
context -- an unsigned integer for a context identifier
message -- an unsigned integer for a message identifier, as returned by the gtk:statusbar-push function
Details:
Forces the removal of a message from the stack of the statusbar. The exact context and message identifier must be specified.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-3-13
Function gtk:statusbar-remove-all (statusbar context)
Arguments:
statusbar -- a gtk:statusbar widget
context -- an integer for a context identifier
Details:
Forces the removal of all messages from the stack of the statusbar with the exact context identifier.
Warning:
The gtk:statusbar implementation is deprecated since 4.10. This widget will be removed in GTK 5.
See also:
#2025-3-13

GtkLockButton

Class gtk:lock-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
permission
The permission property of type g:permission (Read / Write)
The permission controlling this button.
text-lock
The text-lock property of type :string (Read / Write / Construct)
The text to display when prompting the user to lock.
Default value: "Lock"
text-unlock
The text-unlock property of type :string (Read / Write / Construct)
The text to display when prompting the user to unlock.
Default value: "Unlock"
tooltip-lock
The tooltip-lock property of type :string (Read / Write / Construct)
The tooltip to display when prompting the user to lock.
Default value: "Dialog is unlocked.\n Click to prevent further changes"
tooltip-not-authorized
The tooltip-not-authorized property of type :string (Read / Write / Construct)
The tooltip to display when prompting the user cannot obtain authorization.
Default value: "System policy prevents changes. \nContact your system administrator"
tooltip-unlock
The tooltip-unlock property of type :string (Read / Write / Construct)
The tooltip to display when prompting the user to unlock.
Default value: "Dialog is locked.\nClick to make changes"
Returned by:
Slot Access Functions:
Details:
The gtk:lock-button widget is a widget that can be used in control panels or preference dialogs to allow users to obtain and revoke authorizations needed to operate the controls.

Figure: GtkLockButton

The required authorization is represented by a g:permission object. Concrete implementations of the g:permission class may use the PolicyKit library or some other authorization framework. To obtain a PolicyKit-based g:permission object, use the polkit_permission_new() function.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
2025-3-13
Accessor gtk:lock-button-permission (object)
Syntax:
(gtk:lock-button-permission object) => permission
(setf (gtk:lock-button-permission object) permission)
Arguments:
object -- a gtk:lock-button widget
permission -- a g:permission object, or nil
Details:
Accessor of the permission slot of the gtk:lock-button class. The gtk:lock-button-permission function obtains the permission that controls the lock button. The (setf gtk:lock-button-permission) function sets the permission.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Accessor gtk:lock-button-text-lock (object)
Syntax:
(gtk:lock-button-text-lock object) => text
(setf (gtk:lock-button-text-lock object) text)
Arguments:
object -- a gtk:lock-button widget
text -- a string with the text to display
Details:
Accessor of the text-lock slot of the gtk:lock-button class. The text to display when prompting the user to lock.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Accessor gtk:lock-button-text-unlock (object)
Syntax:
(gtk:lock-button-text-unlock object) => text
(setf (gtk:lock-button-text-unlock object) text)
Arguments:
object -- a gtk:lock-button widget
text -- a string with the text to display
Details:
Accessor of the text-unlock slot of the gtk:lock-button class. The text to display when prompting the user to unlock.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Accessor gtk:lock-button-tooltip-lock (object)
Syntax:
(gtk:lock-button-tooltip-lock object) => tooltip
(setf (gtk:lock-button-tooltip-lock object) tooltip)
Arguments:
object -- a gtk:lock-button widget
tooltip -- a string with the tooltip to display
Details:
Accessor of the tooltip-lock slot of the gtk:lock-button class. The tooltip to display when prompting the user to lock.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Accessor gtk:lock-button-tooltip-not-authorized (object)
Syntax:
(gtk:lock-button-tooltip-not-authorized object) => tooltip
(setf (gtk:lock-button-tooltip-not-authorized object) tooltip)
Arguments:
object -- a gtk:lock-button widget
tooltip -- a string with the tooltip to display
Details:
Accessor of the tooltip-lock slot of the gtk:lock-button class. The tooltip to display when prompting the user cannot obtain authorization.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Accessor gtk:lock-button-tooltip-unlock (object)
Syntax:
(gtk:lock-button-tooltip-unlock object) => tooltip
(setf (gtk:lock-button-tooltip-unlock object) tooltip)
Arguments:
object -- a gtk:lock-button widget
tooltip -- a string with the tooltip to display
Details:
Accessor of the tooltip-lock slot of the gtk:lock-button class. The tooltip to display when prompting the user to unlock.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13
Function gtk:lock-button-new (permission)
Arguments:
permission -- a g:permission object
Returns:
The new gtk:lock-button widget.
Details:
Creates a new lock button which reflects the permission.
Warning:
The gtk:lock-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
#2025-3-13

GtkVolumeButton

Class gtk:volume-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
use-symbolic
The use-symbolic property of type :boolean (Read / Write)
Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal, potentially colorful icons will be used.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:volume-button class is a subclass of the gtk:scale-button class that has been tailored for use as a volume control widget with suitable icons, tooltips and accessible labels.

Figure: GtkVolumeButton
Warning:
The gtk:volume-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
2025-3-13
Accessor gtk:volume-button-use-symbolic (object)
Syntax:
(gtk:volume-button-use-symbolic object) => setting
(setf (gtk:volume-button-use-symbolic object) setting)
Arguments:
object -- a gtk:volume-button widget
setting -- a boolean whether to use symbolic icons
Details:
Accessor of the use-symbolic slot of the gtk:volume-button class. Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal, potentially colorful icons will be used.
Warning:
The gtk:volume-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
2025-3-13
Function gtk:volume-button-new ()
Returns:
The new gtk:volume-button widget.
Details:
Creates a volume button, with a range between 0.0 and 1.0, with a stepping of 0.02. Volume values can be obtained and modified using the functions from the gtk:scale-button class.
Warning:
The gtk:volume-button implementation has been deprecated since version 4.10 and should not be used in newly written code. This widget will be removed in GTK 5.
See also:
2025-3-13

GtkEntryCompletion

Class gtk:entry-completion
Superclasses:
gtk:buildable, gtk:cell-layout, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
cell-area
The cell-area property of type gtk:cell-area (Read / Write / Construct)
The cell area used to layout cell renderers in the tree view column. If no area is specified when creating the entry completion with the gtk:entry-completion-new-with-area function a horizontally oriented gtk:cell-area-box object will be used.
inline-completion
The inline-completion property of type :boolean (Read / Write)
Determines whether the common prefix of the possible completions should be inserted automatically in the text entry. Note that this requires the text-column property to be set, even if you are using a custom match function.
Default value: false
inline-selection
The inline-selection property of type :boolean (Read / Write)
Determines whether the possible completions on the popup will appear in the text entry as you navigate through them.
Default value: false
minimum-key-length
The minimum-key-length property of type :int (Read / Write)
The minimum length of the search key in order to look up matches.
Allowed values: >= 0
Default value: 1
model
The model property of type gtk:tree-model (Read / Write)
The model to find matches in.
popup-completion
The popup-completion property of type :boolean (Read / Write)
Determines whether the possible completions should be shown in a popup window.
Default value: true
popup-set-width
The popup-set-width property of type :boolean (Read / Write)
Determines whether the completions popup window will be resized to the width of the entry.
Default value: true
popup-single-match
The popup-single-match property of type :boolean (Read / Write)
Determines whether the completions popup window will shown for a single possible completion. You probably want to set this to false if you are using inline completion.
Default value: true
text-column
The text-column property of type :int (Read / Write)
The column of the model containing the strings. Note that the strings must be UTF-8.
Allowed values: >= -1
Default value: -1
Returned by:
Slot Access Functions:
Details:
The gtk:entry-completion object is an auxiliary object to be used in conjunction with the gtk:entry widget to provide the completion functionality. It implements the gtk:cell-layout interface, to allow the user to add extra cells to the gtk:tree-view widget with completion matches.

"Completion functionality" means that when the user modifies the text in the text entry, the gtk:entry-completion object checks which rows in the model match the current content of the text entry, and displays a list of matches. By default, the matching is done by comparing the text case-insensitively against the text column of the model, see the gtk:entry-completion-text-column function, but this can be overridden with a custom match function, see the gtk:entry-completion-set-match-func function.

When the user selects a completion, the content of the text entry is updated. By default, the content of the text entry is replaced by the text column of the model, but this can be overridden by connecting to the "match-selected" signal and updating the text entry in the signal handler. Note that you should return true from the signal handler to suppress the default behaviour.

To add completion functionality to a text entry, use the gtk:entry-completion function.

The gtk:entry-completion object uses a gtk:tree-model-filter model to represent the subset of the entire model that is currently matching. While the gtk:entry-completion widget "match-selected" and "cursor-on-match" signals take the original model and an iterator pointing to that model as arguments, other callbacks and signals, such as a gtk:cell-layout-data-func function or the "apply-attributes" signal, will generally take the filter model as argument. As long as you are only calling the gtk:tree-model-get function, this will make no difference to you. If for some reason, you need the original model, use the gtk:tree-model-filter-model function. Do not forget to use the gtk:tree-model-filter-convert-iter-to-child-iter function to obtain a matching iterator.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
Signal Details:
The "cursor-on-match" signal
lambda (widget model iter)    :run-last      
widget
The gtk:entry-completion object which received the signal.
model
The gtk:tree-model object containing the matches.
iter
The gtk:tree-iter instance positioned at the selected match.
Returns
True if the signal has been handled.
Gets emitted when a match from the cursor is on a match of the list. The default behaviour is to replace the contents of the text entry with the contents of the text column in the row pointed to by iter. Note that model is the model that was passed to the gtk:entry-completion-model function.
The "insert-prefix" signal
lambda (widget prefix)    :run-last      
widget
The gtk:entry-completion object which received the signal.
prefix
The string with the common prefix of all possible completions.
Returns
True if the signal has been handled.
Gets emitted when the inline autocompletion is triggered. The default behaviour is to make the text entry display the whole prefix and select the newly inserted part. Applications may connect to this signal in order to insert only a smaller part of the prefix into the text entry, for example, the text entry used in the gtk:file-chooser widget inserts only the part of the prefix up to the next '/'.
The "match-selected" signal
lambda (widget model iter)    :run-last      
widget
The gtk:entry-completion object which received the signal.
model
The gtk:tree-model object containing the matches.
iter
The gtk:tree-iter instance positioned at the selected match.
Returns
True if the signal has been handled.
Gets emitted when a match from the list is selected. The default behaviour is to replace the contents of the text entry with the contents of the text column in the row pointed to by iter. Note that model is the model that was passed to the gtk:entry-completion-model function.
The "no-matches" signal
lambda (widget)    :run-last      
widget
The gtk:entry-completion object which received the signal.
Gets emitted when the entry completion is out of suggestions.
See also:
2024-5-2
Accessor gtk:entry-completion-cell-area (object)
Syntax:
(gtk:entry-completion-cell-area object) => area
(setf (gtk:entry-completion-cell-area object) area)
Arguments:
object -- a gtk:entry-completion object
area -- a gtk:cell-area object
Details:
Accessor of the cell-area slot of the gtk:entry-completion class. The cell area used to layout cell renderers in the tree view column. If no area is specified when creating the entry completion with the gtk:entry-completion-new-with-area function a horizontally oriented gtk:cell-area-box object will be used.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-inline-completion (object)
Syntax:
(gtk:entry-completion-inline-completion object) => setting
(setf (gtk:entry-completion-inline-completion object) setting)
Arguments:
object -- a gtk:entry-completion object
setting -- true to do inline completion
Details:
Accessor of the inline-completion slot of the gtk:entry-completion class. The gtk:entry-completion-inline-completion function returns whether the common prefix of the possible completions should be automatically inserted in the text entry. The (setf gtk:entry-completion-inline-completion) function sets the property.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-inline-selection (object)
Syntax:
(gtk:entry-completion-inline-selection object) => setting
(setf (gtk:entry-completion-inline-selection object) setting)
Arguments:
object -- a gtk:entry-completion object
setting -- true to do inline selection
Details:
Accessor of the inline-selection slot of the gtk:entry-completion class. The gtk:entry-completion-inline-selection function returns true if inline selection mode is turned on. The (setf gtk:entry-completion-inline-selection) function sets whether it is possible to cycle through the possible completions inside the text entry.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-minimum-key-length (object)
Syntax:
(gtk:entry-completion-minimum-key-length object) => length
(setf (gtk:entry-completion-minimum-key-length object) length)
Arguments:
object -- a gtk:entry-completion object
length -- an integer for the minimum length of the key in order to start completing
Details:
Accessor of the minimum-key-length slot of the gtk:entry-completion class. The gtk:entry-completion-minimum-key-length function returns the minimum key length as set for the entry completion. The (setf gtk:entry-completion-minimum-key-length) function sets the length of the search key for the entry completion to be at least length.

This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway, that is, a too large dataset.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2025-3-19
Accessor gtk:entry-completion-model (object)
Syntax:
(gtk:entry-completion-model object) => model
(setf (gtk:entry-completion-model object) model)
Arguments:
object -- a gtk:entry-completion object
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:entry-completion class. The gtk:entry-completion-model function returns the gtk:tree-model object, or nil if none is currently being used. The (setf gtk:entry-completion-model) function sets the model for a entry completion. If the entry completion already has a model set, it will remove it before setting the new model. If model is nil, then it will unset the model.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-popup-completion (object)
Syntax:
(gtk:entry-completion-popup object) => setting
(setf (gtk:entry-completion-popup object) setting)
Arguments:
object -- a gtk:entry-completion object
setting -- true to do popup completion
Details:
Accessor of the popup-completion slot of the gtk:entry-completion class. The gtk:entry-completion-popup-completion function returns whether the completions should be presented in a popup window. The (setf gtk:entry-completion-popup-completion) function sets whether the completions should be presented in a popup window.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-3
Accessor gtk:entry-completion-popup-set-width (object)
Syntax:
(gtk:entry-completion-popup-set-width object) => setting
(setf (gtk:entry-completion-popup-set-width object) setting)
Arguments:
object -- a gtk:entry-completion object
setting -- true to make the width of the popup the same as the text entry
Details:
Accessor of the popup-set-width slot of the gtk:entry-completion class. The gtk:entry-completion-popup-set-width function returns whether the completion popup window will be resized to the width of the text entry. The (setf gtk:entry-completion-popup-set-width) function sets whether the completion popup window will be resized to be the same width as the text entry.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-popup-single-match (object)
Syntax:
(gtk:entry-completion-popup-single-match object) => setting
(setf (gtk:entry-completion-popup-single-match object) setting)
Arguments:
object -- a gtk:entry-completion object
setting -- true if the popup should appear even for a single match
Details:
Accessor of the popup-single-match slot of the gtk:entry-completion class. The gtk:entry-completion-popup-single-match function returns true if the popup window will appear regardless of the number of matches. The (setf gtk:entry-completion-popup-single-match) function sets whether the completion popup window will appear even if there is only a single match. You may want to set this to false if you are using inline completion.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-5-2
Accessor gtk:entry-completion-text-column (object)
Syntax:
(gtk:entry-completion-text-column) => column
(setf (gtk:entry-completion-text-column object) column)
Arguments:
object -- a gtk:entry-completion object
column -- an integer for the column in the model of the completion to get strings from
Details:
Accessor of the text-column slot of the gtk:entry-completion class. The gtk:entry-completion-text-column function returns the column in the model of the completion to get strings from. The (setf gtk:entry-completion-text-column) function is a convenience function for setting up the most used case: a completion list with just strings.

This function will set up completion to have a list displaying all, and just, strings in the completion list, and to get those strings from column in the model of completion.

This functions creates and adds a gtk:cell-renderer-text object for the selected column. If you need to set the text column, but do not want the cell renderer, use the g:object-property function to set the text-column property directly.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2025-3-19
Function gtk:entry-completion-new ()
Returns:
The newly created gtk:entry-completion object.
Details:
Creates a new entry completion.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-5-2
Function gtk:entry-completion-new-with-area (area)
Arguments:
area -- a gtk:cell-area object used to layout cells
Returns:
The newly created gtk:entry-completion object.
Details:
Creates a new entry completion using the specified area to layout cells in the underlying gtk:tree-view-column object for the drop-down menu.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-19
Function gtk:entry-completion-entry (completion)
Arguments:
completion -- a gtk:entry-completion object
Returns:
The gtk:widget object the entry completion has been attached to.
Details:
Gets the widget the entry completion has been attached to.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2025-3-19
Callback gtk:entry-completion-match-func
Syntax:
lambda (completion key iter) => result
Arguments:
completion -- a gtk:entry-completion object
key -- a string to match, normalized and case-folded
iter -- a gtk:tree-iter iterator indicating the row to match
result -- true if iter should be displayed as a possible completion for key
Details:
A callback function which decides whether the row indicated by iter matches a given key, and should be displayed as a possible completion for key. Note that key is normalized and case-folded, see the g_utf8_normalize() and g_utf8_casefold() functions. If this is not appropriate, match functions have access to the unmodified key via the (gtk:entry-text (gtk:entry-completion-entry completion)) function call.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-5-3
Function gtk:entry-completion-set-match-func (completion func)
Arguments:
completion -- a gtk:entry-completion object
func -- a gtk:entry-completion-match-func callback function to use
Details:
Sets the match function for the entry completion to be func. The match function is used to determine if a row should or should not be in the completion list.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-5-2
Function gtk:entry-completion-compute-prefix (completion key)
Arguments:
completion -- a gtk:entry-completion object
key -- a string for the text to complete for
Returns:
The string with the common prefix all rows starting with key or nil if no row matches key.
Details:
Computes the common prefix that is shared by all rows in completion that start with key. If no row matches key, the nil values will be returned. Note that a text column must have been set for this function to work, see the gtk:entry-completion-text-column function for details.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2025-3-19
Function gtk:entry-completion-complete (completion)
Arguments:
completion -- a gtk:entry-completion object
Details:
Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2025-3-19
Function gtk:entry-completion-completion-prefix (completion)
Arguments:
completion -- a gtk:entry-completion object
Returns:
The string with the prefix for the current completion.
Details:
Get the original text entered by the user that triggered the completion or nil if there is no completion ongoing.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-5-2
Function gtk:entry-completion-insert-prefix (completion)
Arguments:
completion -- a gtk:entry-completion object
Details:
Requests a prefix insertion.
Warning:
The gtk:entry-completion implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2025-3-19

GtkTreePath

GBoxed gtk:tree-iter
Declaration:
(glib:define-gboxed-cstruct tree-iter "GtkTreeIter"
  (:export t
   :type-initializer "gtk_tree_iter_get_type")
  (stamp :int :initform 0)
  (user-data pointer-as-integer :initform 0)
  (user-data-2 pointer-as-integer :initform 0)
  (user-data-3 pointer-as-integer :initform 0))  
Values:
stamp
The unique stamp to catch invalid iterators.
user-data
Model specific data.
user-data-2
Model specific data.
user-data-3
Model specific data.
Details:
The gtk:tree-iter structure is the primary structure for accessing a gtk:tree-model object. Models are expected to put a unique integer in the stamp member, and put model specific data in the three user-data members.
Warning:
The gtk:tree-iter implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-2-25
GBoxed gtk:tree-path
Declaration:
(glib:define-gboxed-opaque tree-path "GtkTreePath"
  :export t
  :type-initializer "gtk_tree_path_get_type"
  :alloc (%tree-path-new))  
Returned by:
Details:
An opaque structure representing a path to a row in a model.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-new ()
Returns:
The newly created gtk:tree-path instance.
Details:
Creates a new tree path.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-new-first ()
Returns:
The new gtk:tree-path instance.
Details:
Creates a new tree path. The string representation of this tree path is "0".
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-new-from-indices (&rest indices)
Arguments:
indices -- integers for the indices
Returns:
The newly created gtk:tree-path instance.
Details:
Creates a new tree path from the given indices.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-2-25
Function gtk:tree-path-new-from-string (pathstr)
Arguments:
pathstr -- a string representation of a tree path
Returns:
The newly created gtk:tree-path instance, or nil.
Details:
Creates a tree path initialized from pathstr. The pathstr argument is expected to be a colon separated list of numbers. For example, the string "10:4:0" would create a tree path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the 1st child of that 5th child. If an invalid path string is passed in, nil is returned.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-2-25
Function gtk:tree-path-copy (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The new gtk:tree-path instance.
Details:
Creates a new tree path as a copy of path.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-append-index (path index)
Arguments:
path -- a gtk:tree-path instance
index -- an integer for the index
Returns:
The gtk:tree-path instance.
Details:
Appends a new index to the tree path. As a result, the depth of path is increased.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-prepend-index (path index)
Arguments:
path -- a gtk:tree-path instance
index -- an integer for the index
Returns:
The gtk:tree-path instance.
Details:
Prepends a new index to the tree path. As a result, the depth of path is increased.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-depth (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The integer with the depth of path.
Details:
Returns the current depth of the tree path.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-indices (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The list of integers with the current indices, or nil.
Details:
Returns the current indices of the tree path. This is a list of integers, each representing a node in a model. The length of the list can be obtained with the gtk:tree-path-depth function.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-2-25
Function gtk:tree-path-compare (path1 path2)
Arguments:
path1 -- a gtk:tree-path instance
path2 -- a gtk:tree-path instance to compare with
Returns:
The integer with the relative position of path1 and path2.
Details:
Compares two paths. If path1 appears before path2 in a model, then -1 is returned. If path2 appears before path1, then 1 is returned. If the two nodes are equal, then 0 is returned.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-2-25
Function gtk:tree-path-next (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The new gtk:tree-path instance.
Details:
Moves path to point to the next node at the current depth.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-prev (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The gtk:tree-path instance to point to the previous node, if it exists, otherwise nil.
Details:
Moves the tree path to point to the previous node at the current depth, if it exists.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-up (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The gtk:tree-path instance to point to the parent node, if it has a parent, otherwise nil.
Details:
Moves the tree path to point to its parent node, if it has a parent.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-down (path)
Arguments:
path -- a gtk:tree-path instance
Details:
Moves path to point to the first child of the current tree path.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-is-ancestor (path descendant)
Arguments:
path -- a gtk:tree-path instance
descendant -- another gtk:tree-path instance
Returns:
True if descendant is contained inside path.
Details:
Returns true if descendant is a descendant of path.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-is-descendant (path ancestor)
Arguments:
path -- a gtk:tree-path instance
ancestor -- another gtk:tree-path instance
Returns:
True if ancestor contains path somewhere below it.
Details:
Returns true if path is a descendant of ancestor.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-path-to-string (path)
Arguments:
path -- a gtk:tree-path instance
Returns:
The string with the representation of the tree path.
Details:
Generates a string representation of the tree path. This string is a ':' separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.
Warning:
The gtk:tree-path implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11

GtkTreeRowReference

GBoxed gtk:tree-row-reference
Declaration:
(glib:define-gboxed-opaque gtk:tree-row-reference "GtkTreeRowReference"
  :export t
  :type-initializer "gtk_tree_row_reference_get_type"
  :alloc (error "GtkTreeRowReference cannot be created from the Lisp side."))  
Returned by:
Details:
The gtk:tree-row-reference instance tracks model changes so that it always refers to the same row, a gtk:tree-path instance refers to a position, not a fixed row. Create a new gtk:tree-row-reference instance with the gtk:tree-row-reference-new function.

Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-row-reference-new (model path)
Arguments:
model -- a gtk:tree-model object
path -- a valid gtk:tree-path instance to monitor
Returns:
The newly allocated gtk:tree-row-reference instance, or nil.
Details:
Creates a row reference based on path. This reference will keep pointing to the node pointed to by path, so long as it exists. Any changes that occur on model are propagated, and the row reference is updated appropriately. If path is not a valid path in model, then nil is returned.
Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-row-reference-copy (reference)
Arguments:
reference -- a gtk:tree-row-reference instance
Returns:
The new gtk:tree-row-reference instance.
Details:
Copies a tree row reference.
Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-row-reference-model (reference)
Arguments:
reference -- a gtk:tree-row-reference instance
Returns:
The gtk:tree-model object.
Details:
Returns the model that the row reference is monitoring.
Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-row-reference-path (reference)
Arguments:
reference -- a gtk:tree-row-reference instance
Returns:
The current gtk:tree-path instance, or nil.
Details:
Returns a path that the row reference currently points to, or nil if the path pointed to is no longer valid.
Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11
Function gtk:tree-row-reference-valid (reference)
Arguments:
reference -- a gtk:tree-row-reference, or nil
Returns:
True if reference points to a valid path.
Details:
Returns true if reference is non-nil and refers to a current valid path.
Warning:
The gtk:tree-row-reference implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-1-11

GtkTreeModel

GFlags gtk:tree-model-flags
Declaration:
(gobject:define-gflags "GtkTreeModelFlags" tree-model-flags
  (:export t
   :type-initializer "gtk_tree_model_flags_get_type")
  (:iters-persist 1)
  (:list-only 2))  
Values:
:iters-persist
Iterators survive all signals emitted by the model.
:list-only
The model is a list only, and never has children.
Details:
These flags indicate various properties of a gtk:tree-model object. They are returned by the gtk:tree-model-flags function, and must be static for the lifetime of the model. A more complete description of the :iters-persist value can be found in the overview of this section.
See also:
2025-2-25
Interface gtk:tree-model
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:tree-model interface defines a generic tree interface for use by the gtk:tree-view widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer just has to implement this interface on their own data type for it to be viewable by a gtk:tree-view widget.

The model is represented as a hierarchical tree of strongly typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column is determined by using the GType system, that is "gint", "GtkButton", "gpointer", and so on. The types are homogeneous per column across all nodes. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made.

In order to make life simpler for programmers who do not need to write their own specialized model, two generic models are provided - the gtk:tree-store and the gtk:list-store classes. To use these, the developer simply pushes data into these models as necessary. These models provide the data structure as well as all appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For the vast majority of trees and lists, these two models are sufficient.

Models are accessed on a node/column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. There are two structures used to reference a particular node in a model. They are the gtk:tree-path and the gtk:tree-iter structures. Most of the interface consists of operations on a gtk:tree-iter iterator.

A tree path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. The gtk:tree-path structure can be converted into either an array of unsigned integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the offset at that level. Thus, the path '0' refers to the root node and the path '2:4' refers to the fifth child of the third node.

By contrast, a gtk:tree-iter iterator is a reference to a specific node on a specific model. It is a generic structure with an integer and three generic pointers. These are filled in by the model in a model-specific way. One can convert a path to an iterator by calling the gtk:tree-model-iter function. These iterators are the primary way of accessing a model and are similar to the iterators used by the gtk:text-buffer class. They are generally statically allocated on the stack and only used for a short time. The model interface defines a set of operations using them for navigating the model.

It is expected that models fill in the iterator with private data. For example, the gtk:list-store model, which is internally a simple linked list, stores a list node in one of the pointers. The gtk:tree-model-sort class stores an array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled with a unique stamp per model. This stamp is for catching errors resulting from using invalid iterators with a model.

The life cycle of an iterator can be a little confusing at first. Iterators are expected to always be valid for as long as the model is unchanged (and does not emit a signal). The model is considered to own all outstanding iterators and nothing needs to be done to free them from the user's point of view. Additionally, some models guarantee that an iterator is valid for as long as the node it refers to is valid (most notably the gtk:tree-store and gtk:list-store models). Although generally uninteresting, as one always has to allow for the case where iterators do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the :iters-persist flag was added to indicate this behavior.
Examples:
To show some common operation of a model, some examples are provided. The first example shows three ways of getting the iterator at the location '3:2:5'. While the first method shown is easier, the second is much more common, as you often get paths from callbacks.
;; Three ways of getting the iter pointing to the location
(let (path iter parent)
  ;; Get the iterator from a string
  (setf iter (gtk:tree-model-iter-from-string model "3:2:5"))

;; Get the iterator from a path (setf path (gtk:tree-path-new-from-string "3:2:5")) (setf iter (gtk:tree-model-iter model path))

;; Walk the tree to find the iterator (setf parent (gtk:tree-model-iter-nth-child model nil 3)) (setf parent (gtk:tree-model-iter-nth-child model parent 2)) (setf iter (gtk:tree-model-iter-nth-child model parent 5)) ... )
The second example shows a quick way of iterating through a list and getting a value from each row.
(do* ((model (gtk:tree-view-model view))             ; get the model
      (iter (gtk:tree-model-iter-first model)        ; get first iter
            (gtk:tree-model-iter-next model iter)))  ; get next iter
     ((not iter))                                    ; until iter is nil
     ;; Get a value and do something with the data
     (let ((value (gtk:tree-model-value model iter col-yearborn)))
       (gtk:list-store-set-value model iter
                                       col-yearborn
                                       (1+ value))))    
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
Signal Details:
The "row-changed" signal
lambda (model path iter)    :run-last      
model
The gtk:tree-model object on which the signal is emitted.
path
The gtk:tree-path instance identifying the changed row.
iter
The valid gtk:tree-iter iterator pointing to the changed row.
The signal is emitted when a row in the model has changed.
The "row-deleted" signal
lambda (model path)    :run-first      
model
The gtk:tree-model object on which the signal is emitted.
path
The gtk:tree-path instance identifying the row.
The signal is emitted when a row has been deleted. Note that no iterator is passed to the signal handler, since the row is already deleted. This should be called by models after a row has been removed. The location pointed to by path should be the location that the row previously was at. It may not be a valid location anymore.
The "row-has-child-toggled" signal
lambda (model path iter)    :run-last      
model
The gtk:tree-model object on which the signal is emitted.
path
The gtk:tree-path instance identifying the row.
iter
The valid gtk:tree-iter iterator pointing to the row.
The signal is emitted when a row has gotten the first child row or lost its last child row.
The "row-inserted" signal
lambda (model path iter)    :run-first      
model
The gtk:tree-model object on which the signal is emitted.
path
The gtk:tree-path instance identifying the new row.
iter
The valid gtk:tree-iter iterator pointing to the new row.
The signal is emitted when a new row has been inserted in the model. Note that the row may still be empty at this point, since it is a common pattern to first insert an empty row, and then fill it with the desired values.
The "rows-reordered" signal
lambda (model path iter order)    :run-first      
model
The gtk:tree-model object on which the signal is emitted.
path
The gtk:tree-path instance identifying the tree node whose children have been reordered.
iter
The valid gtk:tree-iter iterator pointing to the node whose children have been reordered.
order
The array of integers mapping the current position of each child to its old position before the re-ordering, that is order[newpos] = oldpos.
The signal is emitted when the children of a node in the gtk:tree-model object have been reordered. Note that the signal is not emitted when rows are reordered by drag and drop, since this is implemented by removing and then reinserting the row.
See also:
2025-3-3
Function gtk:tree-model-flags (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The gtk:tree-model-flags value for the flags supported by this interface.
Details:
Returns a set of flags supported by this interface. The flags are a bitwise combination of gtk:tree-model-flags flags. The flags supported should not change during the lifetime of the model.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-n-columns (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The integer with the number of columns.
Details:
Returns the number of columns supported by model.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-column-type (model index)
Arguments:
model -- a gtk:tree-model object
index -- an integer for the column index
Returns:
The g:type-t type ID of the column.
Details:
Returns the type of the column.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-iter (model path)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance
Returns:
The gtk:tree-iter iterator or nil, if the iterator is not set.
Details:
Returns a valid iterator pointing to path. If path does not exist, nil is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-iter-from-string (model pathstr)
Arguments:
model -- a gtk:tree-model object
pathstr -- a string representation of a gtk:tree-path object
Returns:
The gtk:tree-iter iterator.
Details:
Returns a valid iterator pointing to pathstr, if it exists. Otherwise, nil is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-iter-first (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The gtk:tree-iter iterator.
Details:
Returns the first iterator in the tree, the one at the path "0". Returns nil if the tree is empty.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-path (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator
Returns:
The newly created gtk:tree-path instance.
Details:
Returns a tree path referenced by the given iterator.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-value (model iter column)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator
column -- an integer for the column to lookup the value at
Returns:
The value at column.
Details:
Returns the value at column.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2025-3-3
Function gtk:tree-model-iter-next (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator
Returns:
The gtk:tree-iter iterator.
Details:
Returns the iterator to the node following iter at the current level. If there is no next iterator, nil is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-previous (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator
Returns:
The gtk:tree-iter iterator.
Details:
Returns the iterator to the previous node at the current level. If there is no previous iterator, nil is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-children (model parent)
Arguments:
model -- a gtk:tree-model object
parent -- a gtk:tree-iter iterator, or nil
Returns:
The gtk:tree-iter iterator.
Details:
Returns the iterator to the first child of parent. If parent has no children, nil is returned. The parent iterator will remain a valid node after this function has been called.

If parent is nil returns the first node. This is equivalent to:
(gtk:tree-model-iter-first model)  
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-has-child (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator to test for children
Returns:
True if iter has children.
Details:
Returns true if iter has children, nil otherwise.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-n-children (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator, or nil
Returns:
The integer with the number of children of iter.
Details:
Returns the number of children that iter has. As a special case, if iter is nil, then the number of toplevel nodes is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-nth-child (model parent index)
Arguments:
model -- a gtk:tree-model object
parent -- a gtk:tree-iter iterator to get the child from, or nil
index -- an integer for the index of the desired child
Returns:
The gtk:tree-iter iterator to the nth child.
Details:
Returns the iterator to the child of parent, using the given index. The first index is 0. If index is too big, or parent has no children, nil is returned. The parent iterator will remain a valid node after this function has been called. As a special case, if parent is nil, then the nth root node is returned.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-iter-parent (model child)
Arguments:
model -- a gtk:tree-model object
child -- a gtk:tree-iter iterator
Returns:
The gtk:tree-iter iterator to the parent.
Details:
Returns the iterator to the parent of child. If child is at the toplevel, and does not have a parent, then nil is returned. The child iterator will remain a valid node after this function has been called.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-string-from-iter (model iter)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter instance
Returns:
The string representation of iter.
Details:
Generates a string representation of the iterator. This string is a ':' separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-get (model iter &rest colums)
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator to a row
columns -- a list of integers for the column numbers
Returns:
The list of values for the columns.
Details:
Gets the value of one or more cells in the row referenced by iter. The variable argument list should contain integer column numbers. For example, to get a value from columns 1 and 3, you would write:
(gtk:tree-model-get model iter 1 3)  
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Callback gtk:tree-model-foreach-func
Syntax:
lambda (model path iter) => result
Arguments:
model -- a gtk:tree-model object being iterated
path -- a current gtk:tree-path instance
iter -- a current gtk:tree-iter iterator
result -- true to stop iterating, false to continue
Details:
Type of the callback function passed to the gtk:tree-model-foreach function to iterate over the rows in a tree model.
See also:
#2025-3-3
Function gtk:tree-model-foreach (model func)
Arguments:
model -- a gtk:tree-model object
func -- a gtk:tree-model-foreach-func callback function to be called on each row
Details:
Calls func on each node in model in a depth-first fashion. If func returns true, then the tree ceases to be walked, and the gtk:tree-model-foreach function returns.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-row-changed (model path iter)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance pointing to the changed row
iter -- a valid gtk:tree-iter iterator pointing to the changed row
Details:
Emits the "row-changed" signal on model.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-row-inserted (model path iter)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance pointing to the inserted row
iter -- a valid gtk:tree-iter iterator pointing to the inserted row
Details:
Emits the "row-inserted" signal on model.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-row-has-child-toggled (model path iter)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance pointing to the changed row
iter -- a valid gtk:tree-iter iterator pointing to the changed row
Details:
Emits the "row-has-child-toggled" signal on model. This should be called by models after the child state of a node changes.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-row-deleted (model path)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance pointing to the previous location of the deleted row
Details:
Emits the "row-deleted" signal on model. This should be called by models after a row has been removed. The location pointed to by path should be the location that the row previously was at. It may not be a valid location anymore.

Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3
Function gtk:tree-model-rows-reordered (model path iter order)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance pointing to the tree node whose children have been reordered
iter -- a valid gtk:tree-iter iterator pointing to the node whose children have been reordered, or nil if the depth of path is 0
order -- a list of integers mapping the current position of each child to its old position before the re-ordering
Details:
Emits the "rows-reordered" signal on model. This should be called by models when their rows have been reordered.
Warning:
The gtk:tree-model implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2025-3-3

GtkTreeSelection

Class gtk:tree-selection
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
mode
The mode property of type gtk:selection-mode (Read / Write)
The selection mode.
Default value: :single
Slot Access Functions:
Details:
The gtk:tree-selection object is a helper object to manage the selection for a gtk:tree-view widget. The gtk:tree-selection object is automatically created when a new gtk:tree-view widget is created, and cannot exist independentally of this widget. The primary reason the gtk:tree-selection objects exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the gtk:tree-view widget instead of a separate function.

The gtk:tree-selection object is gotten from a gtk:tree-view widget by calling the gtk:tree-view-selection function. It can be manipulated to check the selection status of the tree view, as well as select and deselect individual rows. Selection is done completely tree view side. As a result, multiple tree views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the tree view without expanding its parents first.

One of the important things to remember when monitoring the selection of a tree view is that the "changed" signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a "changed" signal.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
Signal Details:
The "changed" signal
lambda (selection)    :run-first      
selection
The gtk:tree-selection object which received the signal.
Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened.
See also:
2024-11-5
Accessor gtk:tree-selection-mode (object)
Syntax:
(gtk:tree-selection-mode object) => mode
(setf (gtk:tree-selection-mode object) mode)
Arguments:
object -- a gtk:tree-selection object
mode -- a gtk:selection-mode value
Details:
Accessor of the mode slot of the gtk:tree-selection class. The gtk:tree-selection-mode function gets the current selection mode of the selection. The (setf gtk:tree-selection-mode) function sets the selection mode. If the previous type was :multiple, then the anchor is kept selected, if it was previously selected.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-11-5
Callback gtk:tree-selection-func
Syntax:
lambda (selection model path selected) => result
Arguments:
selection -- a gtk:tree-selection object
mode -- a gtk:tree-model object being viewed
path -- a gtk:tree-path instance of the row in question
selected -- true, if the path is currently selected
result -- true, if the selection state of the row can be toggled
Details:
A callback function used by the gtk:tree-selection-set-select-function function to filter whether or not a row may be selected. It is called whenever the selection state of a row might change. A return value of true indicates to selection that it is okay to change the selection.
See also:
#2024-11-5
Function gtk:tree-selection-set-select-function (selection func)
Arguments:
selection -- a gtk:tree-selection object
func -- a gtk:tree-selection-func selection function, may be nil
Details:
Sets the selection function. If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected. The select function should return true if the state of the node may be toggled, and false if the state of the node should be left unchanged.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-tree-view (selection)
Arguments:
selection -- a gtk:tree-selection object
Returns:
The gtk:tree-view object.
Details:
Returns the tree view associated with selection.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-11-5
Function gtk:tree-selection-selected (selection)
Arguments:
selection -- a gtk:tree-selection object
Returns:
The gtk:tree-iter iterator of the selected node, or nil if there is no selected node.
Details:
Returns the iterator to the currently selected node if the selection mode is set to the values :single or :browse of the gtk:selection-mode enumeration. This function will not work if you use the selection mode :multiple.
Notes:
As a convenience the C implementation also gets the current model of the tree view wiget associated with the selection. Use the gtk:tree-selection-tree-view and gtk:tree-view-model functions instead to get the model.
Examples:
(let* ((model (gtk:tree-view-model view))
       (selection (gtk:tree-view-selection view))
       ;; This will only work in single or browse selection mode
       (iter (gtk:tree-selection-selected selection)))
  (if iter
      ;; A row is selected
      ...
      ;; No row is selected
      ...
  ... )    
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Callback gtk:tree-selection-foreach-func
Syntax:
lambda (model path iter)
Arguments:
model -- a gtk:tree-model object being viewed
path -- a gtk:tree-path instance of a selected row
iter -- a gtk:tree-iter instance pointing to a selected row
Details:
A callback function used by the gtk:tree-selection-selected-foreach function to map all selected rows. It will be called on every selected row in the view.
See also:
#2024-11-5
Function gtk:tree-selection-selected-foreach (selection func)
Arguments:
selection -- a gtk:tree-selection object
func -- a gtk:tree-selection-foreach-func callback function to call for each selected node
Details:
Calls a function for each selected node. Note that you cannot modify the tree view or selection from within this function. As a result, the gtk:tree-selection-selected-rows function might be more useful.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-selected-rows (selection)
Arguments:
selection -- a gtk:tree-selection object
Returns:
The list containing a gtk:tree-path instance for each selected row.
Details:
Creates a list of path of all selected rows. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of gtk:tree-row-reference objects. To do this, you can use the gtk:tree-row-reference-new function.
Notes:
As a convenience the C implementation also gets the current model of the tree view wiget associated with the selection. Use the gtk:tree-selection-tree-view and gtk:tree-view-model functions instead to get the model.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-11-5
Function gtk:tree-selection-count-selected-rows (selection)
Arguments:
selection -- a gtk:tree-selection object
Returns:
The integer with the number of rows selected.
Details:
Returns the number of rows that have been selected in the tree.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-select-path (selection path)
Arguments:
selection -- a gtk:tree-selection object
path -- a gtk:tree-path instance to be selected
Details:
Select the row at path.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-unselect-path (selection path)
Arguments:
selection -- a gtk:tree-selection object
path -- a gtk:tree-path instance to be unselected
Details:
Unselects the row at path.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-path-is-selected (selection path)
Arguments:
selection -- a gtk:tree-selection object
path -- a gtk:tree-path instance to check selection on
Returns:
True if path is selected.
Details:
Returns true if the row pointed to by path is currently selected. If path does not point to a valid location, false is returned.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-select-iter (selection iter)
Arguments:
selection -- a gtk:tree-selection object
iter -- a gtk:tree-iter iterator to be selected
Details:
Selects the specified iterator.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-unselect-iter (selection iter)
Arguments:
selection -- a gtk:tree-selection object
iter -- a gtk:tree-iter iterator to be unselected
Details:
Unselects the specified iterator.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-iter-is-selected (selection iter)
Arguments:
selection -- a gtk:tree-selection object
iter -- a valid gtk:tree-iter iterator
Returns:
True, if iter is selected.
Details:
Returns true if the row at iter is currently selected.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-select-all (selection)
Arguments:
selection -- a gtk:tree-selection object
Details:
Selects all the nodes. The selection argument must be set to :multiple mode.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-unselect-all (selection)
Arguments:
selection -- a gtk:tree-selection object
Details:
Unselects all the nodes.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-select-range (selection start end)
Arguments:
selection -- a gtk:tree-selection object
start -- an initial gtk:tree-path node of the range
end -- a final gtk:tree-path node of the range
Details:
Selects a range of nodes, determined by start and end inclusive. The selection argument must be set to :multiple mode.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:tree-selection-unselect-range (selection start end)
Arguments:
selection -- a gtk:tree-selection object
start -- an initial gtk:tree-path node of the range
end -- a initial gtk:tree-path node of the range
Details:
Unselects a range of nodes, determined by start and end inclusive.
Warning:
The gtk:tree-selection implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-11-5

GtkTreeViewColumn

GEnum gtk:tree-view-column-sizing
Declaration:
(gobject:define-genum "GtkTreeViewColumnSizing" tree-view-column-sizing
  (:export t
   :type-initializer "gtk_tree_view_column_sizing_get_type")
  (:grow-only 0)
  (:autosize 1)
  (:fixed 2))  
Values:
:grow-only
Columns only get bigger in reaction to changes in the model.
:autosize
Columns resize to be the optimal size everytime the model changes.
:fixed
Columns are a fixed numbers of pixels wide.
Details:
The sizing method the tree view column uses to determine its width. Please note that the :autosize value is inefficient for large tree views, and can make tree view columns appear choppy.
See also:
2024-4-27
Class gtk:tree-view-column
Superclasses:
gobject:initially-unowned, gtk:buildable, gtk:cell-layout, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
alignment
The alignment property of type :float (Read / Write)
The alignment of the tree view column header text or widget, 0.0 for left, 0.5 for center, and 1.0 for right alignment.
Allowed values: [0,1]
Default value: 0
cell-area
The cell-area property of type gtk:cell-area (Read / Write / Construct)
The cell area used to layout cell renderers for this tree view column. If no cell area is specified when creating the tree view column a horizontally oriented gtk:cell-area-box object will be used.
clickable
The clickable property of type :boolean (Read / Write)
Whether the tree view column header can be clicked.
Default value: false
expand
The expand property of type :boolean (Read / Write)
The tree view column gets share of extra width allocated to the widget.
Default value: false
fixed-width
The fixed-width property of type :int (Read / Write)
The current fixed width of the tree view column.
Allowed values: >= 1
Default value: 1
max-width
The max-width property of type :int (Read / Write)
The maximum allowed width of the tree view column.
Allowed values: >= -1
Default value: -1
min-width
The min-width property of type :int (Read / Write )
The minimum allowed width of the tree view column.
Allowed values: >= -1
Default value: -1
reorderable
The reorderable property of type :boolean (Read / Write)
Whether the tree view column can be reordered around the headers.
Default value: false
resizable
The resizable property of type :boolean (Read / Write)
Whether the column is user-resizable.
Default value: false
sizing
The sizing property of type gtk:tree-view-column-sizing (Read / Write)
The resize mode of the tree view column.
Default value: :grow-only
sort-column-id
The sort-column-id property of type :int (Read / Write)
The logical sort column ID this tree view column sorts on when selected for sorting. Setting the sort column ID makes the tree view column header clickable. Set to -1 to make the column unsortable.
Allowed values: >= -1
Default value: -1
sort-indicator
The sort-indicator property of type :boolean (Read / Write)
Whether to show a sort indicator.
Default value: false
sort-order
The sort-order property of type gtk:sort-type (Read / Write)
The sort direction the sort indicator should indicate.
Default value: :ascending
spacing
The spacing property of type :int (Read / Write)
The space which is inserted between cell renderers.
Allowed values: >= 0
Default value: 0
title
The title property of type :string (Read / Write)
The title to appear in the tree view column header.
Default value: ""
visible
The visible property of type :boolean (Read / Write)
Whether to display the tree view column.
Default value: true
widget
The widget property of type gtk:widget (Read / Write)
The widget to put in the tree view column header button instead of column title.
width
The width property of type :int (Read)
The current width of the tree view column.
Allowed values: >= 0
Default value: 0
x-offset
The x-offset property of type :int (Read)
The current x position of the tree view column.
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:tree-view-column object represents a visible column in a gtk:tree-view widget. It allows to set properties of the tree view column header, and functions as a holding pen for the cell renderers which determine how the data in the tree view column is displayed.

Please refer to the tree view widget conceptual overview for an overview of all the objects and data types related to the tree view and how they work together.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
Signal Details:
The "clicked" signal
lambda (column)    :run-last      
column
The gtk:tree-view-column object which emitted the signal.
Emitted when the header of the column has been clicked.
See also:
2024-2-19
Accessor gtk:tree-view-column-alignment (object)
Syntax:
(gtk:tree-view-column-alignment object) => align
(setf (gtk:tree-view-column-alignment object) align)
Arguments:
object -- a gtk:tree-view-column object
align -- a float with the alignment, which is between 0.0 and 1.0 inclusive
Details:
Accessor of the alignment slot of the gtk:tree-view-column class. The gtk:tree-view-column-alignment function returns the current alignment of the title or custom widget inside the tree view column header. The (setf gtk:tree-view-column-alignment) function sets the alignment. The alignment determines the location inside the header button, 0.0 for left, 0.5 for center, 1.0 for right alignment.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-cell-area (object)
Syntax:
(gtk:tree-view-column-cell-area object) => area
(setf (gtk:tree-view-column-cell-area object) area)
Arguments:
object -- a gtk:tree-view-column object
area -- a gtk:cell-area object
Details:
Accessor of the cell-area slot of the gtk:tree-view-column class. The cell area used to layout cell renderers for this tree view column. If no cell area is specified when creating the tree view column a horizontally oriented gtk:cell-area-box object will be used.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-clickable (object)
Syntax:
(gtk:tree-view-column-clickable object) => clickable
(setf (gtk:tree-view-column-clickable object) clickable)
Arguments:
object -- a gtk:tree-view-column object
clickable -- true if the tree view column header is active
Details:
Accessor of the clickable slot of the gtk:tree-view-column class. The gtk:tree-view-column-clickable function returns true if the user can click on the header for the tree view column. The (setf gtk:tree-view-column-clickable) function sets the header to be active if clickable is true. When the header is active, then it can take keyboard focus, and can be clicked.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-expand (object)
Syntax:
(gtk:tree-view-column-expand object) => expand
(setf (gtk:tree-view-column-expand object) expand)
Arguments:
object -- a gtk:tree-view-column object
expand -- true if the tree view column should take available extra space, false if not
Details:
Accessor of the expand slot of the gtk:tree-view-column class. The gtk:tree-view-column-expand function returns true if the tree view column expands to take any available space. The (setf gtk:tree-view-column-expand) function sets the tree view column to take available extra space. This space is shared equally amongst all tree view columns that have the expand set to true. If no column has this option set, then the last column gets all extra space. By default, every column is created with this false.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-fixed-width (object)
Syntax:
(gtk:tree-view-column-fixed-width object) => width
(setf (gtk:tree-view-column-fixed-width object) width)
Arguments:
object -- a gtk:tree-view-column object
width -- an integer with the size to set the tree view column to, must be greater than 0
Details:
Accessor of the fixed-width slot of the gtk:tree-view-column class. The gtk:tree-view-column-fixed-width function gets the fixed width of the tree view column in pixels. The (setf gtk:tree-view-column-fixed-width) function sets the width. This is meaningful only if the sizing property has the :fixed value. The width of the tree view column is clamped to the min/max width for the column. Please note that the min/max width of the column does not actually affect the fixed-width property of the widget, just the actual width when displayed.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-max-width (object)
Syntax:
(gtk:tree-view-column-max-width object) => width
(setf (gtk:tree-view-column-max-width object) width)
Arguments:
object -- a gtk:tree-view-column object
width -- an integer with the maximum width of the tree view column in pixels, or -1
Details:
Accessor of the max-width slot of the gtk:tree-view-column class. The gtk:tree-view-column-max-width function returns the maximum width in pixels of the tree view column, or -1 if no maximum width is set. The (setf gtk:tree-view-column-max-width) function sets the maximum width. If width is -1, then the maximum width is unset. Note, the tree view column can actually be wider than max width if it is the last column in a tree view. In this case, the column expands to fill any extra space.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-min-width (object)
Syntax:
(gtk:tree-view-column-min-width object) => width
(setf (gtk:tree-view-column-min-width object) width)
Arguments:
object -- a gtk:tree-view-column object
width -- an integer with the minimum width of the tree view column in pixels, or -1
Details:
Accessor of the min-width slot of the gtk:tree-view-column class. The gtk:tree-view-column-min-width function returns the minimum width in pixels of the tree view column, or -1 if no minimum width is set. The (setf gtk:tree-view-column-min-width) function sets the minimum width. If width is -1, then the minimum width is unset.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-reorderable (object)
Syntax:
(gtk:tree-view-column-reorderable object) => reorderable
(setf (gtk:tree-view-column-reorderable object) reorderable)
Arguments:
object -- a gtk:tree-view-column object
reorderable -- true, if the tree view column can be reordered
Details:
Accessor of the reorderable slot of the gtk:tree-view-column class. If reorderable is true, then the tree view column can be reordered by the user dragging the header.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-resizable (object)
Syntax:
(gtk:tree-view-column-resizable object) => resizable
(setf (gtk:tree-view-column-resizable object) resizable)
Arguments:
object -- a gtk:tree-view-column object
resizable -- true, if the tree view column can be resized
Details:
Accessor of the resizable slot of the gtk:tree-view-column class. The gtk:tree-view-column-resizable function returns true if the tree view column can be resized by the user.

If resizable is true, then the user can explicitly resize the tree view column by grabbing the outer edge of the column button. If resizable is true and the sizing mode of the tree view column is :autosize, then the sizing mode is changed to :grow-only.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-sizing (object)
Syntax:
(gtk:tree-view-column-sizing object) => type
(setf (gtk:tree-view-column-sizing object) type)
Arguments:
object -- a gtk:tree-view-column object
Details:
Accessor of the sizing slot of the gtk:tree-view-column class. The gtk:tree-view-column-sizing function returns the current sizing type of the tree view column. The (setf gtk:tree-view-column-sizing) sets the sizing type.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-sort-column-id (object)
Syntax:
(gtk:tree-view-column-sort-column-id object) => id
(setf (gtk:tree-view-column-sort-column-id object) id)
Arguments:
object -- a gtk:tree-view-column object
id -- an integer with the sort-column-id of the model to sort on
Details:
Accessor of the sort-column-id slot of the gtk:tree-view-column class. The gtk:tree-view-column-sort-column-id function gets the logical sort column ID that the model sorts on when this tree view column is selected for sorting. The (setf gtk:tree-view-column-sort-column-id) function sets the logical sort column ID. Doing so makes the tree view column header clickable.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-sort-indicator (object)
Syntax:
(gtk:tree-view-column-sort-indicator object) => setting
(setf (gtk:tree-view-column-sort-indicator object) setting)
Arguments:
object -- a gtk:tree-view-column object
setting -- true to display an indicator that the tree view column is sorted
Details:
Accessor of the sort-indicator slot of the gtk:tree-view-column class. Call this function with a setting of true to display an arrow in the header button indicating the tree view column is sorted. Call the gtk:tree-view-column-sort-order function to change the direction of the arrow.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-sort-order (object)
Syntax:
(gtk:tree-view-column-sort-order object) => order
(setf (gtk:tree-view-column-sort-order object) order)
Arguments:
object -- a gtk:tree-view-column object
order -- a gtk:sort-type value
Details:
Accessor of the sort-order slot of the gtk:tree-view-column class. This does not actually sort the model. Use the gtk:tree-view-column-sort-column-id function if you want automatic sorting support. This function is primarily for custom sorting behavior, and should be used in conjunction with the gtk:tree-sortable-sort-column-id function to do that. For custom models, the mechanism will vary.

The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the sort indicator enabled to see anything when calling this function. See the gtk:tree-view-column-sort-indicator function.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-spacing (object)
Syntax:
(gtk:tree-view-column-spacing object) => spacing
(setf (gtk:tree-view-column-spacing object) spacing)
Arguments:
object -- a gtk:tree-view-column object
spacing -- an integer with the distance between cell renderers in pixels
Details:
Accessor of the spacing slot of the gtk:tree-view-column class. The gtk:tree-view-column-spacing function returns the spacing of the tree view column, which is the number of pixels to place between cell renderers packed into it. The (setf gtk:tree-view-column-spacing) function sets the spacing field of the tree view column.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-title (object)
Syntax:
(gtk:tree-view-column-title object) => title
(setf (gtk:tree-view-column-title object) title)
Arguments:
object -- a gtk:tree-view-column object
title -- a string with the title of the tree view column
Details:
Accessor of the title slot of the gtk:tree-view-column class. The gtk:tree-view-column-title function returns the title of the tree view column. The (setf gtk:tree-view-column-title) function sets the title. If a custom widget has been set, then this value is ignored.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-visible (object)
Syntax:
(gtk:tree-view-column-visible object) => visible
(setf (gtk:tree-view-column-visible object) visible)
Arguments:
object -- a gtk:tree-view-column object
visible -- true if the tree view column is visible
Details:
Accessor of the visible slot of the gtk:tree-view-column class. The gtk:tree-view-column-visible function returns whether the tree view column is visible or not. If it is visible, then the tree will show the column. The (setf gtk:tree-view-column-visible) function sets the visibility of the tree view column.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-widget (object)
Syntax:
(gtk:tree-view-column-widget object) => widget
(setf (gtk:tree-view-column-widget object) widget)
Arguments:
object -- a gtk:tree-view-column object
widget -- a gtk:widget child widget, or nil
Details:
Accessor of the widget slot of the gtk:tree-view-column class. The gtk:tree-view-column-widget function returns the child widget in the button on the tree view column header. If a custom widget has not been set then nil is returned. The (setf gtk:tree-view-column-widget) function sets the child widget. If the child widget is nil, then the header button is set with a gtk:label widget set to the title of the tree view column.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-width (object)
Syntax:
(gtk:tree-view-column-width object) => width
Arguments:
object -- a gtk:tree-view-column object
width -- an integer with the current width of the tree view column
Details:
Accessor of the width slot of the gtk:tree-view-column class. The gtk:tree-view-column-width function returns the current size of the tree view column in pixels.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Accessor gtk:tree-view-column-x-offset (object)
Syntax:
(gtk:tree-view-column-x-offset object) => offset
Arguments:
object -- a gtk:tree-view-column object
offset -- an integer with the current x offset in pixels
Details:
Accessor of the x-offset slot of the gtk:tree-view-column class. The gtk:tree-view-column-width function returns the current x offset of the tree view column in pixels.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-19
Function gtk:tree-view-column-new ()
Returns:
The newly created gtk:tree-view-column object.
Details:
Creates a new tree view column.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-3
Function gtk:tree-view-column-new-with-area (area)
Arguments:
area -- a gtk:cell-area object that the newly created tree view column should use to layout cell renderers
Returns:
The newly created gtk:tree-view-column object.
Details:
Creates a new tree view column using area to render its cells.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-8
Function gtk:tree-view-column-new-with-attributes (title renderer &rest attributes)
Arguments:
title -- a string with the title to set the header to
renderer -- a gtk:cell-renderer object
attributes -- pairs of attributes
Returns:
The newly created gtk:tree-view-column object.
Details:
Creates a new tree view column with a number of default values. This is equivalent to calling the gtk:tree-view-column-title, gtk:tree-view-column-pack-start, and gtk:tree-view-column-set-attributes functions on the newly created gtk:tree-view-column object.
Examples:
(let* ((renderer (gtk:cell-renderer-text-new))
       (column (gtk:tree-view-column-new-with-attributes "Example"
                                                         renderer
                                                         "text" 0
                                                         "foreground" 1)))
  ... )  
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-4
Function gtk:tree-view-column-pack-start (column renderer &key expand)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object
expand -- true if the cell renderer is to be given extra space allocated to the tree view column
Details:
Packs the cell renderer into the beginning of the tree view column. If the expand argument is false, then the cell renderer is allocated no more space than it needs. Any unused space is divided evenly between cell renderers for which the expand argument is true.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-pack-end (column renderer &key expand)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object
expand -- true if the cell renderer is to be given extra space allocated to the tree view column
Details:
Packs the cell renderer to the end of the tree view column. If the expand argument is false, then the cell renderer is allocated no more space than it needs. Any unused space is divided evenly between cell renderers for which the expand argument is true.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-clear (column)
Arguments:
column -- a gtk:tree-view-column object
Details:
Unsets all the mappings on all cell renderers on the tree view column.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-add-attribute (column renderer attribute position)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object to set attributes on
attribute -- a string with an attribute on the cell renderer
position -- an integer with the column position on the model
Details:
Adds an attribute mapping to the list in the tree view column. The column argument is the column of the model to get a value from, and the attribute is the parameter on the cell renderer to be set from the value. So for example if column 2 of the model contains strings, you could have the "text" attribute of a gtk:cell-renderer-text object get its values from column 2.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-set-attributes (column renderer &rest attributes)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object we are setting the attributes of
attributes -- pairs of attributes
Details:
Sets the attributes in the list as the attributes of the tree view column. The attributes should be in attribute/column order, as in the gtk:tree-view-column-add-attribute function. All existing attributes are removed, and replaced with the new attributes.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-4
Callback gtk:tree-cell-data-func
Syntax:
lambda (column renderer model iter)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object that is being rendered by the tree view column
model -- a gtk:tree-model object being rendered
iter -- a gtk:tree-iter object of the current row rendered
Details:
A function to set the properties of a cell instead of just using the straight mapping between the cell and the model. This is useful for customizing the cell renderer. For example, a function might get an integer from the tree model, and render it to the "text" attribute of the cell by converting it to its written equivalent. This is set by calling the gtk:tree-view-column-set-cell-data-func function.
See also:
#2024-5-4
Function gtk:tree-view-column-set-cell-data-func (column renderer func)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object
func -- a gtk:tree-cell-data-func callback function to use
Details:
Sets the callback function to use for the tree view column. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of the tree view column cell renderer as appropriate. The func argument may be nil to remove an older one.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-clear-attributes (column renderer)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object to clear the attribute mapping on
Details:
Clears all existing attributes previously set, for example, with the gtk:tree-view-column-set-attributes function.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-clicked (column)
Arguments:
column -- a gtk:tree-view-column object
Details:
Emits the "clicked" signal on the tree view column. This function will only work if the tree view column is clickable.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-button (column)
Arguments:
column -- a gtk:tree-view-column object
Returns:
The gtk:widget object with the button for the tree view column header.
Details:
Returns the button used in the tree view column header.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-cell-set-cell-data (column model iter expander expanded)
Arguments:
column -- a gtk:tree-view-column object
model -- a gtk:tree-model to to get the cell renderer's attributes from
iter -- a gtk:tree-iter to to get the cell renderer's attributes from
expander -- true, if the row has children
expanded -- true, if the row has visible children
Details:
Sets the cell renderer based on the tree model and iter. That is, for every attribute mapping in the tree view column, it will get a value from the column on the iter, and use that value to set the attribute on the cell renderer. This is used primarily by the tree view.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-cell-size (column)
Arguments:
column -- a gtk:tree-view-column object
Returns:
xoffset -- an integer with the x offset of a cell relative to area
yoffset -- an integer with the y offset of a cell relative to area
width -- an integer with the width needed to render a cell
height -- an integer with the height needed to render a cell
Details:
Obtains the width and height needed to render the column. This is used primarily by the tree view.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-8
Function gtk:tree-view-column-cell-position (column renderer)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object
Returns:
offset -- an integer with the horizontal position of the cell within the tree view column
width -- an integer with the width of the cell
Details:
Obtains the horizontal position and width of a cell in a tree view column. If the cell is not found in the column, nil is returned.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-2-19
Function gtk:tree-view-column-cell-is-visible (column)
Arguments:
column -- a gtk:tree-view-column object
Returns:
True, if any of the cells packed into the tree view column are currently visible.
Details:
Returns true if any of the cells packed into the tree view column are visible. For this to be meaningful, you must first initialize the cells with the gtk:tree-view-column-cell-set-cell-data function.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-focus-cell (column renderer)
Arguments:
column -- a gtk:tree-view-column object
renderer -- a gtk:cell-renderer object
Details:
Sets the current keyboard focus to be at renderer, if the column contains 2 or more editable and activatable cells.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-queue-resize (column)
Arguments:
column -- a gtk:tree-view-column object
Details:
Flags the tree view column, and the cell renderers added to this column, to have their sizes renegotiated.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8
Function gtk:tree-view-column-tree-view (column)
Arguments:
column -- a gtk:tree-view-column object
Returns:
The gtk:tree-view widget wherein the tree view column has been inserted if any, nil otherwise.
Details:
Returns the tree view wherein the tree view column has been inserted. If the column is currently not inserted in any tree view, nil is returned.
Warning:
The gtk:tree-view-column implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-8

GtkTreeView

GEnum gtk:tree-view-drop-position
Declaration:
(gobject:define-genum "GtkTreeViewDropPosition" tree-view-drop-position
  (:export t
   :type-initializer "gtk_tree_view_drop_position_get_type")
  (:before 0)
  (:after 1)
  (:into-or-before 2)
  (:into-or-after 3))  
Values:
:before
Dropped row is inserted before.
:after
Dropped row is inserted after.
:into-or-before
Dropped row becomes a child or is inserted before.
:into-or-after
Dropped row becomes a child or is inserted after.
Details:
An enumeration for determining where a dropped row goes in a tree view.
See also:
2024-4-27
GEnum gtk:tree-view-grid-lines
Declaration:
(gobject:define-genum "GtkTreeViewGridLines" tree-view-grid-lines
  (:export t
   :type-initializer "gtk_tree_view_grid_lines_get_type")
  (:none 0)
  (:horizontal 1)
  (:vertical 2)
  (:both 3))  
Values:
:none
No grid lines.
:horizontal
Horizontal grid lines.
:vertical
Vertical grid lines.
:both
Horizontal and vertical grid lines.
Details:
Used to indicate which grid lines to draw in a tree view.
See also:
2024-4-27
Class gtk:tree-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
activate-on-single-click
The activate-on-single-click property of type :boolean (Read / Write)
Specifies whether the "row-activated" signal will be emitted after a single click.
Default value: false
enable-grid-lines
The enable-grid-lines property of type gtk:tree-view-grid-lines (Read / Write)
Whether grid lines should be drawn in the tree view.
Default value: :none
enable-search
The enable-search property of type :boolean (Read / Write)
Whether the tree view allows user to search through columns interactively.
Default value: true
enable-tree-lines
The enable-tree-lines property of type :boolean (Read / Write)
Whether tree lines should be drawn in the tree view.
Default value: false
expander-column
The expander-column property of type gtk:tree-view-column (Read / Write)
The column for the expander column.
fixed-height-mode
The fixed-height-mode property of type :boolean (Read / Write)
Setting this property to true speeds up the tree view by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see the gtk:tree-view-fixed-height-mode function for more information on this option.
Default value: false
headers-clickable
The headers-clickable property of type :boolean (Read / Write)
Whether column headers respond to click events.
Default value: true
headers-visible
The headers-visible property of type :boolean (Read / Write)
Wether to show the column header buttons.
Default value: true
hover-expand
The hover-expand property of type :boolean (Read / Write)
Enables or disables the hover expansion mode of the tree view. Hover expansion makes rows expand or collapse if the pointer moves over them.
Default value: false
hover-selection
The hover-selection property of type :boolean (Read / Write)
Enables or disables the hover selection mode of the tree view. Hover selection makes the selected row follow the pointer. Currently, this works only for the :single and :browse selection modes.
Default value: false
level-indentation
The level-indentation property of type :int (Read / Write)
The extra indentation for each level.
Allowed values: >= 0
Default value: 0
model
The model property of type gtk:tree-model (Read / Write)
The model for the tree view.
reorderable
The reorderable property of type :boolean (Read / Write)
The tree view is reorderable.
Default value: false
rubber-banding
The rubber-banding property of type :boolean (Read / Write)
Whether to enable selection of multiple items by dragging the mouse pointer.
Default value: false
search-column
The search-column property of type :int (Read / Write)
Model column to search through during interactive search.
The allowed values: >= -1
Default value: -1
show-expanders
The show-expanders property of type :boolean (Read / Write)
True if the view has expanders.
Default value: true
tooltip-column
The tooltip-column property of type :int (Read / Write)
The column in the model containing the tooltip texts for the rows.
Allowed values: >= -1
Default value: -1
Returned by:
Slot Access Functions:
Details:
Widget that displays any object that implements the gtk:tree-model interface.

Figure: GtkTreeView

Please refer to the tree widget conceptual overview for an overview of all the objects and data types related to the tree widget and how they work together.

Several different coordinate systems are exposed in the gtk:tree-view API. These are:

Figure: Tree view coordinates

Coordinate systems in the gtk:tree-view API:
Widget coordinates
Coordinates relative to the widget.
Bin window coordinates
Coordinates relative to the window that the gtk:tree-view widget renders to.
Tree coordinates
Coordinates relative to the entire scrollable area of the gtk:tree-view widget. These coordinates start at (0, 0) for row 0 of the tree.
Several functions are available for converting between the different coordinate systems. The most common translations are between widget and bin window coordinates and between bin window and tree coordinates. For the former you can use the gtk:tree-view-convert-widget-to-bin-window-coords function (and vice versa), for the latter the gtk:tree-view-convert-bin-window-to-tree-coords function (and vice versa).
GtkTreeView as GtkBuildable:
The gtk:tree-view implementation of the gtk:buildable interface accepts gtk:tree-view-column objects as <child> elements and exposes the internal gtk:tree-selection object in UI definitions.

Example: A UI definition fragment with the gtk:tree-view widget
<object class="GtkTreeView" id="treeview">
  <property name="model">liststore1</property>
  <child>
    <object class="GtkTreeViewColumn" id="test-column">
      <property name="title">Test</property>
      <child>
        <object class="GtkCellRendererText" id="test-renderer"/>
        <attributes>
          <attribute name="text">1</attribute>
        </attributes>
      </child>
    </object>
  </child>
  <child internal-child="selection">
    <object class="GtkTreeSelection" id="selection">
      <signal name="changed" handler="on_treeview_selection_changed"/>
    </object>
  </child>
</object>    
CSS nodes:
treeview.view
├── header
│   ├── <column header>
┊   ┊
│   ╰── <column header>
│
╰── [rubberband]    
The gtk:tree-view implementation has a main CSS node with name treeview and .view style class. It has a subnode with name header, which is the parent for all the column header widgets' CSS nodes. For rubberband selection, a subnode with name rubberband is used.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Use the gtk:list-view implementation for lists, and the gtk:column-view implementation for tabular lists.
Signal Details:
The "columns-changed" signal
lambda (view)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
The number of columns of the tree view has changed.
The "cursor-changed" signal
lambda (view)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
The position of the cursor (focused cell) has changed.
The "expand-collapse-cursor-row" signal
lambda (view arg1 arg2)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
arg1
a boolean without description
arg2
a boolean without description
Returns
a boolean without description
The "move-cursor" signal
lambda (view step direction)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
step
The granularity of the move, as a value of the gtk:movement-step enumeration. The :logical-positions, :visual-positions, :display-lines, :pages and :buffer-ends values are supported. The :logical-positions and :visual-positions values are treated identically.
direction
The integer with the direction to move: +1 to move forwards, -1 to move backwards. The resulting movement is undefined for all other values.
Returns
True if step is supported, false otherwise.
Keybinding signal which gets emitted when the user presses one of the cursor keys. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. In contrast to the gtk:tree-view-get-cursor and gtk:tree-view-set-cursor-on-cell functions when moving horizontally "move-cursor" does not reset the current selection.
The "row-activated" signal
lambda (view path column)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
path
The gtk:tree-path instance for the activated row.
column
The gtk:tree-view-column object in which the activation occurred.
The signal is emitted when the gtk:tree-view-row-activated function is called or the user double clicks a tree view row. It is also emitted when a non-editable row is selected and one of the Space, Shift+Space, Return or Enter keys is pressed. For selection handling refer to the tree widget conceptual overview as well as the gtk:tree-selection API documentation.
The "row-collapsed" signal
lambda (view iter path)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
iter
The gtk:tree-iter iterator of the collapsed row.
path
The gtk:tree-path instance that points to the row.
The given row has been collapsed (child nodes are hidden).
The "row-expanded" signal
lambda (view iter path)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
iter
The gtk:tree-iter iterator of the expanded row.
path
The gtk:tree-path instance that points to the row.
The given row has been expanded (child nodes are shown).
The "select-all" signal
lambda (view)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
The "select-cursor-parent" signal
lambda (view)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
The "select-cursor-row" signal
lambda (view arg)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
arg
a boolean without description
Returns
a boolean without description
The "start-interactive-search" signal
lambda (view)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
The "test-collapse-row" signal
lambda (view iter path)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
iter
The gtk:tree-iter iterator of the row to collapsed.
path
The gtk:tree-path instance that points to the row.
Returns
False to allow collapsing, true to reject.
The given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows.
The "test-expand-row" signal
lambda (view iter path)    :run-last      
view
The gtk:tree-view widget on which the signal is emitted.
iter
The gtk:tree-iter iterator of the row to expand.
path
The gtk:tree-path instance that points to the row.
Returns
False to allow expansion, true to reject.
The given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows.
The "toggle-cursor-row" signal
lambda (view)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
The "unselect-all" signal
lambda (view)    :action      
view
The gtk:tree-view widget on which the signal is emitted.
See also:
2025-3-30
Accessor gtk:tree-view-activate-on-single-click (object)
Syntax:
(gtk:tree-view-activate-on-single-click object) => setting
(setf (gtk:tree-view-activate-on-single-click object) setting)
Arguments:
object -- a gtk:tree-view widget
setting -- a boolean that is true to emit the "row-activated" signal on a single click
Details:
Accessor of the activate-on-single-click slot of the gtk:tree-view class. Cause the "row-activated" signal to be emitted on a single click instead of a double click.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-enable-grid-lines (object)
Syntax:
(gtk:tree-view-enable-grid-lines object) => setting
(setf (gtk:tree-view-enable-grid-lines object) setting)
Arguments:
object -- a gtk:tree-view widget
setting -- a boolean whether grid lines should be drawn
Details:
Accessor of the enable-grid-lines slot of the gtk:tree-view class. Whether grid lines should be drawn in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Syntax:
(gtk:tree-view-enable-search object) => enable
(setf (gtk:tree-view-enable-search object) enable)
Arguments:
object -- a gtk:tree-view widget
enable -- true, if the user can search interactively
Details:
Accessor of the enable-search slot of the gtk:tree-view class. If the enable-search property is set, then the user can type in text to search through the tree view interactively, this is sometimes called "typeahead find". Note that even if the property is false, the user can still initiate a search using the "start-interactive-search" key binding.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-enable-tree-lines (object)
Syntax:
(gtk:tree-view-enable-tree-lines object) => enable
(setf (gtk:tree-view-enable-tree-lines object) enable)
Arguments:
object -- a gtk:tree-view widget
enable -- true, to enable tree line drawing, false otherwise
Details:
Accessor of the enable-tree-lines slot of the gtk:tree-view class. The gtk:tree-view-enable-tree-lines function returns whether or not tree lines are drawn in the tree view. The (setf gtk:tree-view-enable-tree-lines) function sets whether to draw lines. This does not have any visible effects for lists.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-expander-column (object)
Syntax:
(gtk:tree-view-expander-column object) => column
(setf (gtk:tree-view-expander-column object) column)
Arguments:
object -- a gtk:tree-view widget
column -- a gtk:tree-view-column object with the column to draw the expander arrow at, or nil
Details:
Accessor of the expander-column slot of the gtk:tree-view class. The gtk:tree-view-expander-column function returns the column that is the current expander column. The (setf gtk:tree-view-expander-column) function sets the column to draw the expander arrow at. It must be in the tree view. If the column argument is nil, then the expander arrow is always at the first visible column.

If you do not want expander arrow to appear in your tree, set the expander column to a hidden column.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-fixed-height-mode (object)
Syntax:
(gtk:tree-view-fixed-height-mode object) => enable
(setf (gtk:tree-view-fixed-height-mode object) enable)
Arguments:
object -- a gtk:tree-view widget
enable -- true to enable fixed height mode
Details:
Accessor of the fixed-height-mode slot of the gtk:tree-view class. The gtk:tree-view-fixed-height-mode function returns whether fixed height mode is turned on for the tree view. The (setf gtk:tree-view-fixed-height-mode) function enables or disables the fixed height mode.

Fixed height mode speeds up the tree view by assuming that all rows have the same height. Only enable this option if all rows are the same height and all columns have the :fixed value of the gtk:tree-view-column-sizing enumeration.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-headers-clickable (object)
Syntax:
(gtk:tree-view-headers-clickable object) => setting
(setf (gtk:tree-view-headers-clickable object) setting)
Arguments:
object -- a gtk:tree-view widget
setting -- true if the columns are clickable
Details:
Accessor of the headers-clickable slot of the gtk:tree-view class. The gtk:tree-view-headers-clickable function returns whether all header columns are clickable. The (setf gtk:tree-view-headers-clickable) function allow the column title buttons to be clicked.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-headers-visible (object)
Syntax:
(gtk:tree-view-headers-visible object) => visible
(setf (gtk:tree-view-headers-visible object) visible)
Arguments:
object -- a gtk:tree-view widget
visible -- true if the headers are visible
Details:
Accessor of the headers-visible slot of the gtk:tree-view class. The gtk:tree-view-headers-visible function returns true if the headers on the tree view are visible. The (setf gtk:tree-view-headers-visible) function sets the visibility state of the headers.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-hover-expand (object)
Syntax:
(gtk:tree-view-hover-expand object) => expand
(setf (gtk:tree-view-hover-expand object) expand)
Arguments:
object -- a gtk:tree-view widget
expand -- true to enable hover selection mode
Details:
Accessor of the hover-expand slot of the gtk:tree-view class. The gtk:tree-view-hover-expand function returns whether hover expansion mode is turned on for the tree view. The (setf gtk:tree-view-hover-expand) function enables or disables the hover expansion mode. Hover expansion makes rows expand or collapse if the pointer moves over them.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-hover-selection (object)
Syntax:
(gtk:tree-view-hover-selection object) => setting
(setf (gtk:tree-view-hover-selection object) setting)
Arguments:
object -- a gtk:tree-view widget
setting -- true to enable hover selection mode
Details:
Accessor of the hover-selection slot of the gtk:tree-view class. The gtk:tree-view-hover-selection function returns whether hover selection mode is turned on for the tree view. The (setf gtk:tree-view-hover-selection) function enables or disables the hover selection mode. Hover selection makes the selected row follow the pointer. Currently, this works only for the :single and :browse selection modes.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-level-indentation (object)
Syntax:
(gtk:tree-view-level-indentation object) => indentation
(setf (gtk:tree-view-level-indentation object) indentation)
Arguments:
object -- a gtk:tree-view widget
indentation -- an integer with the amount, in pixels, of extra indentation
Details:
Accessor of the level-indentation slot of the gtk:tree-view class. The gtk:tree-view-level-indentation function returns the amount, in pixels, of extra indentation for child levels in the tree view in addition to the default indentation. The (setf gtk:tree-view-level-indentation) function sets the amount of extra indentation.

The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. This does not have any visible effects for lists.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-model (object)
Syntax:
(gtk:tree-view-model object) => model
(setf (gtk:tree-view-model object) model)
Arguments:
objet -- a gtk:tree-view widget
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:tree-view class. The gtk:tree-view-model function returns the model the tree view is based on. Returns nil if the model is unset. The (setf gtk:tree-view-model) function sets the model. If the tree view already has a model set, it will remove it before setting the new model. If the model argument is nil, then it will unset the old model.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-reorderable (object)
Syntax:
(gtk:tree-view-reorderable object) => reorderable
(setf (gtk:tree-view-reorderable object) rorderable)
Arguments:
object -- a gtk:tree-view widget
reorderable -- true, if the tree view can be reordered
Details:
Accessor of the reorderable slot of the gtk:tree-view class. This function is a convenience function to allow you to reorder models that support the gtk:tree-drag-source and the gtk:tree-drag-dest interfaces.

Both the gtk:tree-store and the gtk:list-store classes support these. If the reorderable argument is true, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's "row-inserted" and "row-deleted" signals. The reordering is implemented by setting up the tree view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose.

This function does not give you any degree of control over the order - any reordering is allowed. If more control is needed, you should probably handle drag and drop manually.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-rubber-banding (object)
Syntax:
(gtk:tree-view-rubber-banding object) => enable
(setf (gtk:tree-view-rubber-banding object) enable)
Arguments:
object -- a gtk:tree-view widget
enable -- true, to enable rubber banding
Details:
Accessor of the rubber-banding slot of the gtk:tree-view class. The gtk:tree-view-rubber-banding function returns whether rubber banding is turned on for the tree view. The (setf gtk:tree-view-rubber-banding) function enables or disables rubber banding. If the selection mode is :multiple, rubber banding will allow the user to select multiple rows by dragging the mouse.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-search-column (object)
Syntax:
(gtk:tree-view-search-column object) => column
(setf (gtk:tree-view-search-column object) column)
Arguments:
object -- a gtk:tree-view widget
column -- an integer with the column of the model to search in, or -1 to disable searching
Details:
Accessor of the search-column slot of the gtk:tree-view class. The gtk:tree-view-search-column function gets the column searched on by the interactive search code. The (setf gtk:tree-view-search-column) function sets column as the column where the interactive search code should search in for the current model.

If the search column is set, users can use the "start-interactive-search" key binding to bring up search popup. The enable-search property controls whether simply typing text will also start an interactive search.

Note that the column argument refers to a column of the current model. The search column is reset to -1 when the model is changed.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Accessor gtk:tree-view-show-expanders (object)
Syntax:
(gtk:tree-view-show-expanders object) => enabled
(setf (gtk:tree-view-show-expanders object) enabled)
Arguments:
object -- a gtk:tree-view widget
enabled -- true to enable expander drawing, false otherwise
Details:
Accessor of the show-expanders slot of the gtk:tree-view class. The gtk:tree-view-show-expanders function returns whether or not expanders are drawn in the tree view. The (setf gtk:tree-view-show-expanders) function sets whether to draw and enable expanders and indent child rows in the tree view. When disabled there will be no expanders visible in tree views and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You can set a custom indentation in this case using the gtk:tree-view-level-indentation function. This does not have any visible effects for lists.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Accessor gtk:tree-view-tooltip-column (object)
Syntax:
(gtk:tree-view-tooltip-column object) => column
(setf (gtk:tree-view-tooltip-column object) column)
Arguments:
object -- a gtk:tree-view widget
column -- an integer which is a valid column number for tree view's model
Details:
Accessor of the tooltip-column slot of the gtk:tree-view class. The gtk:tree-view-tooltip-column function returns the column of the tree view's model which is being used for displaying tooltips on the tree view's rows.

If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have the gtk:tree-view widget handle these automatically for you. The column argument should be set to the column in the tree view's model containing the tooltip texts, or -1 to disable this feature.

When enabled, the has-tooltip property will be set to true and the tree view will connect a "query-tooltip" signal handler.

Note that the signal handler sets the text with the gtk:tooltip-set-markup function, so &, <, etc have to be escaped in the text.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-new ()
Returns:
The newly created gtk:tree-view widget.
Details:
Creates a new tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-new-with-model (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The newly created gtk:tree-view widget.
Details:
Creates a new tree view with the model initialized to model.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-selection (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
The gtk:tree-selection object.
Details:
Gets the tree selection associated with the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-columns-autosize (view)
Arguments:
view -- a gtk:tree-view widget
Details:
Resizes all columns to their optimal width. Only works after the tree view has been realized.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-9
Function gtk:tree-view-append-column (view column)
Arguments:
view -- a gtk:tree-view widget
column -- a gtk:tree-view-column object to add
Returns:
The integer with the number of columns in view after appending.
Details:
Appends column to the list of columns in the tree view. If view has fixed height mode enabled, then column must have its sizing property set to be the :fixed value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-remove-column (view column)
Arguments:
view -- a gtk:tree-view widget
column -- a gtk:tree-view-column object to remove
Returns:
The integer with the number of columns in view after removing.
Details:
Removes a column from the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-insert-column (view column pos)
Arguments:
view -- a gtk:tree-view widget
column -- a gtk:tree-view-column object to be inserted
pos -- an integer with the position to insert column in
Returns:
The integer with the number of columns in view after insertion.
Details:
This inserts the column into the tree view at the given position. If the pos argument is -1, then the column is inserted at the end. If view has the fixed-height-mode property enabled, then column must have its sizing property set to be the :fixed value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-insert-column-with-attributes (view pos title renderer &rest attributes)
Arguments:
view -- a gtk:tree-view widget
pos -- an integer with the position to insert the new column in
title -- a string with the title to set the header to
renderer -- a gtk:cell-renderer object
attributes -- pairs of attributes
Returns:
The integer with the number of columns in view after insertion.
Details:
Creates a new gtk:tree-view-column object and inserts it into the tree view at pos. If the pos argument is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. If view has the fixed-height-mode property enabled, then the new column will have its sizing property set to be the :fixed value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-insert-column-with-data-func (view pos title renderer func)
Arguments:
view -- a gtk:tree-view widget
pos -- an integer with the position to insert the new column in
title -- an string with the title to set the header to
renderer -- a gtk:cell-renderer object
func -- a gtk:tree-cell-data-func callback function to set attributes of cell renderer
Returns:
The integer with the number of columns in view after insertion.
Details:
Convenience function that inserts a new column into the tree view with the given cell renderer and a gtk:tree-cell-data-func callback function to set cell renderer attributes (normally using data from the model). See also the gtk:tree-view-column-set-cell-data-func and gtk:tree-view-column-pack-start functions. If view has the fixed-height-mode property enabled, then the new column will have its sizing property set to be the :fixed value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-n-columns (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
The integer with the number of columns in the tree view.
Details:
Queries the number of columns in the given tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-column (view pos)
Arguments:
view -- a gtk:tree-view widget
pos -- an integer with the position of the column, counting from 0
Returns:
The gtk:tree-view-column object, or nil if the position is outside the range of columns.
Details:
Gets the tree view column at the given position in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-columns (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
The list of gtk:tree-view-column objects.
Details:
Returns a list of all the tree view columns currently in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-9
Function gtk:tree-view-move-column-after (view column base)
Arguments:
view -- a gtk:tree-view widget
column -- a gtk:tree-view-column object to be moved
base -- a gtk:tree-view-column object to be moved relative to, or nil
Details:
Moves column to be after to base. If the base argument is nil, then column is placed in the first position.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Callback gtk:tree-view-column-drop-func
Syntax:
lambda (view column prev next) => result
Arguments:
view -- a gtk:tree-view widget
column -- a gtk:tree-view-column object being dragged
prev -- a gtk:tree-view-column object on one side of column
next -- a gtk:tree-view-column object on the other side of column
result -- true, if column can be dropped in this spot
Details:
Callback function type for determining whether column can be dropped in a particular spot as determined by prev and next. In left to right locales, prev is on the left of the potential drop spot, and next is on the right. In right to left mode, this is reversed. This callback function should return true if the spot is a valid drop spot. Please note that returning true does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user.
See also:
#2024-5-4
Function gtk:tree-view-set-column-drag-function (view func)
Arguments:
view -- a gtk:tree-view widget
func -- a gtk:tree-view-column-drop-func callback function to determine which columns are reorderable, or nil
Details:
Sets a user gtk:tree-view-column-drop-func callback function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to func are: a gtk:tree-view widget, a gtk:tree-view-column object being dragged, and the two gtk:tree-view-column objects determining the drop spot. If either of the gtk:tree-view-column arguments for the drop spot are nil, then they indicate an edge. If func is set to be nil, then view reverts to the default behavior of allowing all columns to be dropped everywhere.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-3-10
Function gtk:tree-view-scroll-to-point (view tx ty)
Arguments:
view -- a gtk:tree-view widget
tx -- an integer with the x coordinate of new top-left pixel of visible area, or -1
ty -- an integer with the y coordinate of new top-left pixel of visible area, or -1
Details:
Scrolls the tree view such that the top-left corner of the visible area is tx, ty, where tx and ty are specified in tree coordinates. The tree view must be realized before this function is called. If it is not, you probably want to be using the gtk:tree-view-scroll-to-cell function.

If either tx or ty are -1, then that direction is not scrolled.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-scroll-to-cell (view path column &optional row-align col-align)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance of the row to move to, or nil
column -- a gtk:tree-view-column object to move horizontally to, or nil
row-align -- an optional float with the vertical alignment of the row specified by path, the default is 0.5
col-align -- an optional float with the horizontal alignment of the column specified by column, the default is 0.5
Details:
Moves the alignments of the tree view to the position specified by column and path. If the column argument is nil, then no horizontal scrolling occurs. Likewise, if the path argument is nil no vertical scrolling occurs. At a minimum, one of column or path need to be non-nil. The row-align argument determines where the row is placed, and the col-align argument determines where column is placed. Both are expected to be between 0.0 and 1.0. The 0.0 value means left/top alignment, the 1.0 value means right/bottom alignment, and the 0.5 value means center.

If the cell is currently visible on the screen, nothing is done.

This function only works if the model is set, and path is a valid row on the model. If the model changes before the tree view is realized, the centered path will be modified to reflect this change.
See also:
#2024-3-10
Function gtk:tree-view-set-cursor (view path &key focus start)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance
focus -- a gtk:tree-view-column object, or nil
start -- true if the specified cell should start being edited
Details:
Sets the current keyboard focus to be at path, and selects it. This is useful when you want to focus the user's attention on a particular row. If the focus argument is not nil, then focus is given to the column specified by it. Additionally, if the focus argument is specified, and the start argument is true, then editing should be started in the specified cell. This function is often followed by the gtk:widget-grab-focus function in order to give keyboard focus to the widget. Please note that editing can only happen when the tree view is realized.

If the path argument is invalid for the model, the current cursor (if any) will be unset and the function will return without failing.
See also:
#2024-3-10
Function gtk:tree-view-set-cursor-on-cell (view path &key focus cell start)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance
focus -- a gtk:tree-view-column, or nil
cell -- a gtk:cell-renderer, or nil
start -- true if the specified cell should start being edited
Details:
Sets the current keyboard focus to be at path, and selects it. This is useful when you want to focus the user's attention on a particular row. If the focus argument is not nil, then focus is given to the column specified by it. If the focus and cell arguments are not nil, and the focus argument contains 2 or more editable or activatable cells, then focus is given to the cell specified by cell. Additionally, if the focus argument is specified, and the start argument is true, then editing should be started in the specified cell. This function is often followed by the gtk:widget-grab-focus function in order to give keyboard focus to the widget. Please note that editing can only happen when the tree view is realized.

If the path argument is invalid for the model, the current cursor (if any) will be unset and the function will return without failing.
See also:
#2024-3-10
Function gtk:tree-view-get-cursor (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
path -- a gtk:tree-path instance with the cursor path, or nil
focus -- a gtk:tree-view-column object with the focus column, or nil
Details:
Returns path and focus with the current path and focus column. If the cursor is not currently set, then path will be nil. If no column currently has focus, then focus will be nil.
See also:
2024-3-10
Function gtk:tree-view-row-activated (view path column)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance to be activated
column -- a gtk:tree-view-column object to be activated
Details:
Activates the cell determined by path and column.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-expand-all (view)
Arguments:
view -- a gtk:tree-view widget
Details:
Recursively expands all nodes in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-collapse-all (view)
Arguments:
view -- a gtk:tree-view widget
Details:
Recursively collapses all visible, expanded nodes in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-expand-to-path (view path)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance to a row
Details:
Expands the row at path. This will also expand all parent rows of path as necessary.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-expand-row (view path all)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance to a row
all -- a boolean whether to recursively expand, or just expand immediate children
Returns:
True if the row existed and had children.
Details:
Opens the row so its children are visible.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-collapse-row (view path)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance to a row in the tree view
Returns:
True if the row was collapsed.
Details:
Collapses a row (hides its child rows, if they exist).
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Callback gtk:tree-view-mapping-func
Syntax:
lambda (view path)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance that is expanded
Details:
Callback function used for the gtk:tree-view-map-expanded-rows function.
See also:
#2024-5-4
Function gtk:tree-view-map-expanded-rows (view func)
Arguments:
view -- a gtk:tree-view widget
func -- a gtk:tree-view-mapping-func callback function to be called
Details:
Calls func on all expanded rows.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-row-expanded (view path)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance to test expansion state
Returns:
True if path is expanded.
Details:
Returns true if the node pointed to by path is expanded in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-path-at-pos (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x position to be identified (relative to the bin window)
y -- an integer with the y position to be identified (relative to the bin window)
Returns:
path -- a gtk:tree-path instance, or nil
column -- a gtk:tree-view-column object, or nil
xcell -- an integer with the x coordinate relative to the cell
ycell -- an integer with the y coordinate relative to the cell
Details:
Finds the path at the point (x,y), relative to bin window coordinates. That is, x and y are relative to an events coordinates. Widget relative coordinates must be converted using the gtk:tree-view-convert-widget-to-bin-window-coords function. It is primarily for things like popup menus. If the path argument is non-nil, then it will be filled with the gtk:tree-path instance at that point. If the column argument is non-nil, then it will be filled with the column at that point. The xcell and ycell values return the coordinates relative to the cell background, for example, the background argument passed to the gtk:cell-renderer-snapshot function. This function is only meaningful if view is realized. Therefore this function will always return false if view is not realized or does not have a model.

For converting widget coordinates, for example, the ones you get from the "query-tooltip" signal, please see the gtk:tree-view-convert-widget-to-bin-window-coords function.
See also:
#2024-5-16
Function gtk:tree-view-is-blank-at-pos (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x position to be identified (relative to the bin window)
y -- an integer with the y position to be identified (relative to the bin window)
Returns:
path -- a gtk:tree-path instance, or nil
column -- a gtk:tree-view-column object, or nil
xcell -- an integer with the x coordinate relative to the cell, or nil
ycell -- an integer where the y coordinate relative to the cell, or nil
Details:
Determine whether the point (x,y) in the tree view is blank, that is no cell content nor an expander arrow is drawn at the location. If so, the location can be considered as the background. You might wish to take special action on clicks on the background, such as clearing a current selection, having a custom context menu or starting rubber banding.

The x and y coordinates that are provided must be relative to the bin window coordinates. Widget relative coordinates must be converted using the gtk:tree-view-convert-widget-to-bin-window-coords function.

For converting widget coordinates, for example, the ones you get from the "query-tooltip" signal, please see the gtk:tree-view-convert-widget-to-bin-window-coords function.

The path, column, xcell and ycell arguments will be returned likewise as for the gtk:tree-view-path-at-pos function.
See also:
#2024-3-10
Function gtk:tree-view-cell-area (view path column)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance for the row, or nil to get only horizontal coordinates
column -- a gtk:tree-view-column object for the column, or nil to get only vertical coordinates
Returns:
The gdk:rectangle instance with the cell rectangle.
Details:
Returns the bounding rectangle in bin window coordinates for the cell at the row specified by path and the column specified by column. If the path argument is nil, or points to a path not currently displayed, the y and height fields of the rectangle will be filled with 0. If the column argument is nil, the x and width fields will be filled with 0. The sum of all cell rectangles does not cover the entire tree. There are extra pixels in between rows, for example. The returned rectangle is equivalent to the area argument passed to the gtk:cell-renderer-snapshot function. This function is only valid if the tree view is realized.
See also:
#2024-5-16
Function gtk:tree-view-background-area (view path column)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance for the row, or nil to get only horizontal coordinates
column -- a gtk:tree-view-column object for the column, or nil to get only vertical coordiantes
Returns:
The gdk:rectangle instance with the cell background rectangle.
Details:
Returns the bounding rectangle in the bin window coordinates for the cell at the row specified by path and the column specified by column. If the path argument is nil, or points to a node not found in the tree, the y and height fields of the rectangle will be filled with 0. If the column argument is nil, the x and width fields will be filled with 0. The returned rectangle is equivalent to the background argument passed to the gtk:cell-renderer-snapshot function. These background areas tile to cover the entire bin window. Contrast with the area argument, returned by the gtk:tree-view-cell-area function, which returns only the cell itself, excluding surrounding borders and the tree expander area.
See also:
#2025-3-30
Function gtk:tree-view-visible-rect (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
The gdk:rectangle instance.
Details:
Returns the rectangle with the currently visible region of the tree view buffer, in tree view coordinates. Convert to the bin window coordinates with the gtk:tree-view-convert-tree-to-bin-window-coords function. Tree coordinates start at (0,0) for the first row of the tree view, and cover the entire scrollable area of the tree view.
See also:
#2024-3-10
Function gtk:tree-view-visible-range (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
start -- a gtk:tree-path instance with the start of region, or nil
end -- a gtk:tree-path instance with the end of region, or nil
Details:
Returns start and end to be the first and last visible path. Note that there may be invisible paths in between.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-bin-window-to-tree-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x coordinate relative to bin window
y -- an integer with the y coordinate relative to bin window
Returns:
tx -- an integer with the tree x coordinate
ty -- an integer with the tree y coordinate
Details:
Converts bin window coordinates to coordinates for the tree view (the full scrollable area of the tree view).
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-bin-window-to-widget-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the bin window x coordinate
y -- an integer with the bin window y coordinate
Returns:
wx -- an integer with the widget x coordinate
wy -- an integer with the widget y coordinate
Details:
Converts bin window coordinates to widget relative coordinates.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-tree-to-bin-window-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the tree x coordinate
y -- an integer with the tree y coordinate
Returns:
bx -- an integer with the x coordinate relative to bin window
by -- an integer with the y coordinate relative to bin window
Details:
Converts tree view coordinates, coordinates in full scrollable area of the tree view, to bin window coordinates.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-tree-to-widget-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x coordinate relative to the tree view
y -- an integer with the y coordinate relative to the tree view
Returns:
wx -- an integer with the widget x coordinate
wy -- an integer with the widget y coordinate
Details:
Converts tree view coordinates, coordinates in full scrollable area of the tree, to widget coordinates.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-widget-to-bin-window-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x coordinate relative to the widget
y -- an integer with the y coordinate relative to the widget
Returns:
bx -- an integer with the bin window x coordinate
by -- an integer with the bin window y coordinate
Details:
Converts widget coordinates to coordinates for the bin window.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-convert-widget-to-tree-coords (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the x coordinate relative to the widget
y -- an integer with the y coordinate relative to the widget
Returns:
tx -- an integer with the tree view x coordinate
ty -- an integer with the tree view y coordinate
Details:
Converts widget coordinates to coordinates for the tree view, the full scrollable area of the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-enable-model-drag-dest (view formats actions)
Arguments:
view -- a gtk:tree-view widget
formats -- a gdk:content-formats instance with the target formats that the drag will support
actions -- a gdk:drag-action bitmask of possible actions for a drag from this widget
Details:
Turns the tree view into a drop destination for automatic DND. Calling this method sets the reorderable property to the false value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-enable-model-drag-source (view mask formats actions)
Arguments:
view -- a gtk:tree-view widget
mask -- a gdk:modifier-type mask of allowed buttons to start drag
formts -- a gdk:conent-formats instance with the targt formats that the drag will support
actions -- a gdk:drag-action bitmask of possible actions for a drag from this widget
Details:
Turns the tree view into a drag source for automatic DND. Calling this method sets the reorderable property to the false value.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-unset-rows-drag-source (view)
Arguments:
view -- a gtk:tree-view widget
Details:
Undoes the effect of the gtk:tree-view-enable-model-drag-source function. Calling this method sets the reorderable property to false.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-unset-rows-drag-dest (view)
Arguments:
view -- a gtk:tree-view widget
Details:
Undoes the effect of the gtk:tree-view-enable-model-drag-dest function. Calling this method sets the reorderable property to false.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-set-drag-dest-row (view path pos)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance of the row to highlight, or nil
pos -- a gtk:tree-view-drop-position value wich specifies whether to drop before, after or into the row
Details:
Sets the row that is highlighted for feedback. If path is nil, an existing highlight is removed.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-get-drag-dest-row (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
path -- a gtk:tree-path instance of the highlighted row, or nil
pos -- a gtk:tree-view-drop-position position, or nil
Details:
Gets information about the row that is highlighted for feedback.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-get-dest-row-at-pos (view x y)
Arguments:
view -- a gtk:tree-view widget
x -- an integer with the position to determine the destination row for
y -- an integer with the position to determine the destination row for
Returns:
path -- a gtk:tree-path instance of the highlighted row, or nil
pos -- a gtk:tree-view-drop-position position, or nil
Details:
Determines the destination row for a given position. The arguments x and y are expected to be in widget coordinates. This function is only meaningful if the tree view is realized. Therefore this function will always return nil if tree-view is not realized or does not have a model.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-28
Function gtk:tree-view-create-row-drag-icon (view path)
Arguments:
view -- a gtk:tree-view widget
path -- a gtk:tree-path instance
Returns:
The newly allocated cairo:surface-t instance of the drag icon.
Details:
Creates a cairo:surface-t instance for the representation of the row at path. This image is used for a drag icon.
See also:
#2025-3-30
Callback gtk:tree-view-search-equal-func
Syntax:
lambda (model column key iter data) => result
Arguments:
model -- a gtk:tree-model object being searched
column -- an integer with the search column set by the gtk:tree-view-search-column function
key -- a key string to compare with
iter -- a gtk:tree-iter iterator pointing the row of model that should be compared with key
result -- false, if the row matches, true otherwise
Details:
A callback function used for checking whether a row in model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect.
See also:
#2024-5-4
Function gtk:tree-view-set-search-equal-func (view func)
Arguments:
view -- a gtk:tree-view widget
func -- a gtk:tree-view-search-equal-func callback function to use during the search
Details:
Sets the compare callback function for the interactive search capabilities. Note that for equality the callback function returns false on matches.
See also:
#2024-3-10
Function gtk:tree-view-search-entry (view)
Syntax:
(gtk:tree-view-search-entry view) => entry
(setf (gtk:tree-view-search-entry view) entry)
Arguments:
view -- a gtk:tree-view widget
entry -- a gtk:entry widget the interactive search code of the tree view should use or nil
Details:
Accessor of the gtk:entry widget which is currently in use as interactive search entry for the tree view. The gtk:tree-view-search-entry function returns the search entry which is currently in use as interactive search entry for the tree view. In case the built-in entry is being used, nil will be returned. The (setf gtk:tree-view-search-entry) function sets the search entry.

This is useful when you want to provide a search entry in your interface at all time at a fixed position. Passing nil for entry will make the interactive search code use the built-in popup entry again.
See also:
#2024-3-10
Callback gtk:tree-view-row-separator-func
Syntax:
lambda (model iter) => result
Arguments:
model -- a gtk:tree-model object
iter -- a gtk:tree-iter instance pointing at a row in model
result -- true if the row is a separator
Details:
Callback function type for determining whether the row pointed to by iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the callback function returns.
See also:
2024-4-7
Function gtk:tree-view-set-row-separator-func (view func)
Arguments:
view -- a gtk:tree-view widget
func -- a gtk:tree-view-row-separator-func callback function
Details:
Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is nil, no separators are drawn. This is the default value.
See also:
#2024-3-10
Function gtk:tree-view-is-rubber-banding-active (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
True if a rubber banding operation is currently being done in the tree view.
Details:
Returns whether a rubber banding operation is currently being done in the tree view.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-grid-lines (view)
Syntax:
(gtk:tree-view-grid-lines view) => setting
(setf (gtk:tree-view-grid-lines view) setting)
Arguments:
view -- a gtk:tree-view widget
setting -- a gtk:tree-view-grid-lines value indicating which grid lines to enable
Details:
The gtk:tree-view-grid-lines function returns which grid lines are enabled in the tree view. The (setf gtk:tree-view-grid-lines) function sets which grid lines to draw in the tree view.
See also:
#2024-3-10
Function gtk:tree-view-set-tooltip-row (view tooltip path)
Arguments:
view -- a gtk:tree-view widget
tooltip -- a gtk:tooltip object
path -- a gtk:tree-path instance
Details:
Sets the tip area of tooltip to be the area covered by the row at path. See also the gtk:tree-view-tooltip-column function for a simpler alternative. See also the gtk:tooltip-set-tip-area function.
Warning:
The gtk:tree-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-3-10
Function gtk:tree-view-set-tooltip-cell (view tooltip path column renderer)
Arguments:
view -- a gtk:tree-view widget
tooltip -- a gtk:tooltip object
path -- a gtk:tree-path instance or nil
column -- a gtk:tree-view-column object or nil
renderer -- a gtk:cell-renderer or nil
Details:
Sets the tip area of tooltip to the area path, column and renderer have in common. For example if the path argument is nil and column is set, the tip area will be set to the full area covered by column. See also the gtk:tooltip-set-tip-area function.

Note that if the path argument is not specified and renderer is set and part of a column containing the expander, the tooltip might not show and hide at the correct position. In such cases path must be set to the current node under the mouse cursor for this function to operate correctly.

See also the gtk:tree-view-tooltip-column function for a simpler alternative.
See also:
#2024-3-10
Function gtk:tree-view-tooltip-context (view)
Arguments:
view -- a gtk:tree-view widget
Returns:
x -- an integer with the x coordinate (relative to widget coordinates)
y -- an integer with the y coordinate (relative to widget coordinates)
tip -- a boolean whether this is a keyboard tooltip or not
model -- a gtk:tree-model object or nil
path -- a gtk:tree-path instance or nil
iter -- a gtk:tree-iter iterator or nil
Details:
This function is supposed to be used in a "query-tooltip" signal handler for gtk:tree-view widgets. The x, y and tip values which are received in the signal handler, should be passed to this function without modification.

The return value indicates whether there is a tree view row at the given coordinates (true) or not (false) for mouse tooltips. For keyboard tooltips the row returned will be the cursor row. When true, then any of model, path and iter which have been provided will be set to point to that row and the corresponding model. x and y will always be converted to be relative to view's "bin window" if tip is false.
See also:
#2024-3-10

GtkTreeView Drag & Drop

Interface gtk:tree-drag-source
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Interface for Drag-and-Drop destinations in the gtk:tree-view widget.
Warning:
The gtk:tree-drag-source implementation is deprecated since 4.10. List views use widgets to display their contents. You can use the gtk:drag-source implementation to implement a drag source.
See also:
2024-5-28
Function gtk:tree-drag-source-drag-data-delete (source path)
Arguments:
source -- a gtk:tree-drag-source object
path -- a gtk:tree-path instance with the row that was being dragged
Returns:
True if the row was successfully deleted.
Details:
Asks the gtk:tree-drag-source object to delete the row at path, because it was moved somewhere else via drag-and-drop. Returns false if the deletion fails because path no longer exists, or for some model-specific reason. Should robustly handle a path no longer found in the model.
Warning:
The gtk:tree-drag-source implementation is deprecated since 4.10. Use list models instead.
See also:
#2024-5-1
Function gtk:tree-drag-source-drag-data-get (source path)
Arguments:
source -- a gtk:tree-drag-source object
path -- a gtk:tree-path insance with the row that was dragged
Returns:
The gdk:content-provider instance for the given path or nil if none exists.
Details:
Asks the gtk:tree-drag-source object to return a gdk:content-provider object representing the row at path. Should robustly handle a path no longer found in the model.
Warning:
The gtk:tree-drag-source implementation is deprecated since 4.10. Use list models instead.
See also:
#2024-5-1
Function gtk:tree-drag-source-row-draggable (source path)
Arguments:
source -- a gtk:tree-drag-source object
path -- a gtk:tree-path instance with the row on which user is initiating a drag
Returns:
True if the row can be dragged.
Details:
Asks the gtk:tree-drag-source object whether a particular row can be used as the source of a DND operation. If the source does not implement this interface, the row is assumed draggable.
Warning:
The gtk:tree-drag-source implementation is deprecated since 4.10. Use list models instead.
See also:
#2024-5-1
Interface gtk:tree-drag-dest
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Interface for Drag-and-Drop destinations in the gtk:tree-view widget.
Warning:
The gtk:tree-drag-dest implementation is deprecated since 4.10. List views use widgets to display their contents. You can use the gtk:drop-target implementation to implement a drop destination.
See also:
2024-5-1
Function gtk:tree-drag-dest-drag-data-received (dest path value)
Arguments:
dest -- a gtk:tree-drag-dest object
path -- a gtk:tree-path instance with the row to drop in front of
value -- a g:value instance with the data to drop
Returns:
The boolean whether a new row was created before position dest.
Details:
Asks the gtk:tree-drag-dest object to insert a row before the path dest, deriving the contents of the row from value. If dest is outside the tree so that inserting before it is impossible, false will be returned. Also, false may be returned if the new row is not created for some model-specific reason. Should robustly handle a dest no longer found in the model.
Warning:
The gtk:tree-drag-dest implementation is deprecated since 4.10. Use list models instead.
g:value
See also:
#2024-5-1
Function gtk:tree-drag-dest-row-drop-possible (dest path value)
Arguments:
dest -- a gtk:tree-drag-dest object
path -- a gtk:tree-path instance with the destination row
value -- a g:value instance with the data being dropped
Returns:
True if a drop is possible before dest.
Details:
Determines whether a drop is possible before the given dest, at the same depth as dest. That is, can we drop the data in data at that location. The dest argument does not have to exist. The return value will almost certainly be false if the parent of dest does not exist, though.
Warning:
The gtk:tree-drag-dest implementation is deprecated since 4.10. Use list models instead.
See also:
#2024-5-1
Function gtk:tree-create-row-drag-content (model path)
Arguments:
model -- a gtk:tree-model object
path -- a gtk:tree-path instance with a row in model
Returns:
The new gdk:content-provider object.
Details:
Creates a content provider for dragging path from model.
See also:
#2024-5-1

GtkCellLayout

Interface gtk:cell-layout
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:cell-layout interface is an interface to be implemented by all objects which want to provide a gtk:tree-view-column object like API for packing cells, setting attributes and data functions.

One of the notable features provided by implementations of the gtk:cell-layout interface are attributes. Attributes let you set the properties in flexible ways. They can just be set to constant values like regular properties. But they can also be mapped to a column of the underlying tree model with the gtk:cell-layout-add-attribute function, which means that the value of the attribute can change from cell to cell as they are rendered by the cell renderer. Finally, it is possible to specify a function with the gtk:cell-layout-set-cell-data-func function that is called to determine the value of the attribute for each cell that is rendered.
GtkCellLayouts as GtkBuildable:
Implementations of the gtk:cell-layout interface which also implement the gtk:buildable interface accept gtk:cell-renderer objects as <child> elements in UI definitions. They support a custom <attributes> element for their children, which can contain multiple <attribute> elements. Each <attribute> element has a name attribute which specifies a property of the cell renderer. The content of the element is the attribute value.

Example: A UI definition fragment specifying attributes
<object class="GtkCellView">
  <child>
    <object class="GtkCellRendererText"/>
    <attributes>
      <attribute name="text">0</attribute>
    </attributes>
  </child>
</object>    
Furthermore for implementations of the gtk:cell-layout interface that use a gtk:cell-area object to lay out cells, all gtk:cell-layout objects in GTK use a gtk:cell-area object, cell properties can also be defined in the format by specifying the custom <cell-packing> attribute which can contain multiple <property> elements defined in the normal way.

Example: A UI definition fragment specifying cell properties
<object class="GtkTreeViewColumn">
  <child>
    <object class="GtkCellRendererText"/>
    <cell-packing>
      <property name="align">True</property>
      <property name="expand">False</property>
    </cell-packing>
  </child>
</object>    
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. List views use widgets to display their contents. See the gtk:layout-manager implementation for layout manager delegate objects.
See also:
2024-7-8
Function gtk:cell-layout-pack-start (layout cell &key expand)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object
expand -- true if cell is to be given extra space allocated to layout
Details:
Packs cell into the beginning of layout. If the expand keyword argument is false, then cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true. The default value of the expand keyword argument is true. Note that reusing the same cell renderer is not supported.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-1
Function gtk:cell-layout-pack-end (layout cell &key expand)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object
expand -- true if cell is to be given extra space allocated to layout
Details:
Adds cell to the end of layout. If the expand keyword argument is false, then cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true. The default value of the expand keyword argument is true. Note that reusing the same cell renderer is not supported.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-16
Function gtk:cell-layout-area (layout)
Arguments:
layout -- a gtk:cell-layout object
Returns:
The gtk:cell-area object used by layout.
Details:
Returns the underlying cell area which might be layout if called on a gtk:cell-area object or might be nil if no cell area is used by layout.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-16
Function gtk:cell-layout-cells (layout)
Arguments:
layout -- a gtk:cell-layout object
Returns:
The list of gtk:cell-renderer objects.
Details:
Returns the cell renderers which have been added to the cell layout.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-1
Function gtk:cell-layout-reorder (layout cell position)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object to reorder
position -- an integer with the new position to insert cell at
Details:
Reinserts cell at the given position. Note that cell has already to be packed into layout for this to function properly.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-16
Function gtk:cell-layout-clear (layout)
Arguments:
layout -- a gtk:cell-layout object
Details:
Unsets all the mappings on all renderers on layout and removes all renderers from layout.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-1
Function gtk:cell-layout-set-attributes (layout cell &rest attributes)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object
attributes -- pairs of attributes
Details:
Sets the attributes of layout. The attributes should be in attribute/column order, as in the gtk:cell-layout-add-attribute function. All existing attributes are removed, and replaced with the new attributes.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-1
Function gtk:cell-layout-add-attribute (layout cell attribute column)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object
attribute -- a string with an attribute on the renderer
column -- an integer with the column position on the model to get the attribute from
Details:
Adds an attribute mapping to the list in layout. The column argument is the column of the model to get a value from, and attribute is the parameter on cell to be set from the value. So for example if column 2 of the model contains strings, you could have the text attribute of a gtk:cell-renderer-text object get its values from column 2.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-7-8
Callback gtk:cell-layout-data-func
Syntax:
lambda (layout cell model iter)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object whose value is to be set
model -- a gtk:tree-model object
iter -- a gtk:tree-iter iterator indicating the row to set the value for
Details:
A callback function which should set the value of layout's cell renderer(s) as appropriate.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-3
Function gtk:cell-layout-set-cell-data-func (layout cell func)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object
func -- a gtk:cell-layout-data-func callback function to use, or nil
Details:
Sets the callback function to use for layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of layout's cell renderer(s) as appropriate. The func callback function may be nil to remove a previously set function.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-1
Function gtk:cell-layout-clear-attributes (layout cell)
Arguments:
layout -- a gtk:cell-layout object
cell -- a gtk:cell-renderer object to clear the attribute mapping on
Details:
Clears all existing attributes previously set with the gtk:cell-layout-add-attribute function.
Warning:
The gtk:cell-layout implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-16

GtkCellView

Class gtk:cell-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
cell-area
The cell-area property of type gtk:cell-area (Read / Write / Construct)
The cell area rendering cells. If no cell area is specified when creating the cell view with the gtk:cell-view-new-with-context function a horizontally oriented gtk:cell-area-box object will be used.
cell-area-context
The cell-area-context property of type gtk:cell-area-context (Read / Write / Construct)
The cell area used to compute the geometry of the cell view. A group of cell views can be assigned the same context in order to ensure the sizes and cell alignments match across all the views with the same context. The gtk:combo-box menus uses this to assign the same context to all cell views in the menu items for a single menu, each submenu creates its own context since the size of each submenu does not depend on parent or sibling menus.
draw-sensitive
The draw-sensitive property of type :boolean (Read / Write)
Whether all cells should be draw as sensitive for this view regardless of the actual cell properties. Used to make menus with submenus appear sensitive when the items in submenus might be insensitive.
Default value: false
fit-model
The fit-model property of type :boolean (Read / Write)
Whether the view should request enough space to always fit the size of every row in the model, used by the combo box to ensure the combo box size does not change when different items are selected.
Default value: false
model
The model property of type gtk:tree-model (Read / Write)
The model for the cell view.
Returned by:
Slot Access Functions:
Details:
The gtk:cell-view widget displays a single row of a gtk:tree-model object using a gtk:cell-area object and gtk:cell-area-context object. A gtk:cell-area-context object can be provided to the gtk:cell-view widget at construction time in order to keep the cell view in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with each other like the aligned cells in the menus of a gtk:combo-box widget.

The gtk:cell-view widget is a gtk:orientable widget in order to decide in which orientation the underlying gtk:cell-area-context object should be allocated. Taking the gtk:combo-box menu as an example, cell views should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths).
CSS nodes:
The gtk:cell-view widget has a single CSS node with name cellview.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. List views use widgets to display their contents. You can use the gtk:box widget instead.
See also:
2024-5-20
Accessor gtk:cell-view-cell-area (object)
Syntax:
(gtk:cell-view-cell-area object) => area
(setf (gtk:cell-view-cell-area object) area)
Arguments:
object -- a gtk:cell-view object
area -- a gtk:cell-area object
Details:
Accessor of the cell-area slot of the gtk:cell-view class. If no cell area is specified when creating the cell view with the gtk:cell-view-new-with-context function a horizontally oriented gtk:cell-area-box object will be used.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-7-8
Accessor gtk:cell-view-cell-area-context (object)
Syntax:
(gtk:cell-view-cell-area-context object) => context
(setf (gtk:cell-view-cell-area-context object) context)
Arguments:
object -- a gtk:cell-view object
cellarea -- a gtk:cell-area-context object
Details:
Accessor of the cell-area-context slot of the gtk:cell-view class. A group of cell views can be assigned the same context in order to ensure the sizes and cell alignments match across all the views with the same context. The gtk:combo-box menus uses this to assign the same context to all cell views in the menu items for a single menu, each submenu creates its own context since the size of each submenu does not depend on parent or sibling menus.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Accessor gtk:cell-view-draw-sensitive (object)
Syntax:
(gtk:cell-view-draw-sensitive object) => setting
(setf (gtk:cell-view-draw-sensitive object) setting)
Arguments:
object -- a gtk:cell-view object
setting -- a boolean whether to draw all cells in a sensitive state
Details:
Accessor of the draw-sensitive slot of the gtk:cell-view class. The gtk:cell-view-draw-sensitive function gets whether the cell view is configured to draw all of its cells in a sensitive state. The (setf gtk:cell-view-draw-sensitive) function sets the property.

This is used by gtk:combo-box menus to ensure that rows with insensitive cells that contain children appear sensitive in the parent menu item.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Accessor gtk:cell-view-fit-model (object)
Syntax:
(gtk:cell-view-fit-model object) => setting
(setf (gtk:cell-view-fit-model object) setting)
Arguments:
object -- a gtk:cell-view object
setting -- whether the cell view should request space for the whole model
Details:
Accessor of the fit-model slot of the gtk:cell-view class. The gtk:cell-view-fit-model function gets whether the cell view is configured to request space to fit the entire gtk:tree-model object. The (setf gtk:cell-view-fit-model) function sets the property.

This is used by gtk:combo-box widgets to ensure that the cell view displayed on the combo box's button always gets enough space and does not resize when selection changes.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Accessor gtk:cell-view-model (object)
Syntax:
(gtk:cell-view-model object) => model
(setf (gtk:cell-view-model object) model)
Arguments:
object -- a gtk:cell-view object
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:cell-view class. The gtk:cell-view-model function returns the model for the cell view. If no model is used nil is returned. The (setf gtk:cell-view-model) function sets the model. If the cell view already has a model set, it will remove it before setting the new model. If model is nil, then it will unset the old model.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Function gtk:cell-view-new ()
Returns:
The new gtk:cell-view widget.
Details:
Creates a new cell view.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Function gtk:cell-view-new-with-context (area context)
Arguments:
area -- a gtk:cell-area object to layout cells
context -- a gtk:cell-area-context object in which to calculate cell geometry
Returns:
The newly created gtk:cell-view widget.
Details:
Creates a new cell view with a specific cell area to layout cells and a specific cell area context. Specifying the same context for a handfull of cells lets the underlying area synchronize the geometry for those cells, in this way alignments with cell views for other rows are possible.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-7-8
Function gtk:cell-view-new-with-text (text)
Arguments:
text -- a string with the text to display in the cell view
Returns:
The newly created gtk:cell-view widget.
Details:
Creates a new cell view, adds a gtk:cell-renderer-text object to it, and makes its show text.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Function gtk:cell-view-new-with-markup (markup)
Arguments:
markup -- a string with the text to display in the cell view
Returns:
The newly created gtk:cell-view widget.
Details:
Creates a new cell view, adds a gtk:cell-renderer-text object to it, and makes it show markup. The text can be marked up with the Pango text markup language.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Function gtk:cell-view-new-with-texture (texture)
Arguments:
texture -- a gdk:texture object with the image to display in the cell view
Returns:
The newly created gtk:cell-view widget.
Details:
Creates a new cell view, adds a gtk:cell-renderer-pixbuf object to it, and makes its show texture.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-20
Function gtk:cell-view-displayed-row (cellview)
Syntax:
(gtk:cell-view-display-row cellview) => path
(setf (gtk:cell-view-display-row cellview) path)
Arguments:
cellview -- a gtk:cell-view widget
path -- a gtk:tree-path instance or nil to unset
Details:
The gtk:cell-view-displayed-row function returns a gtk:tree-path instance referring to the currently displayed row. If no row is currently displayed, nil is returned.

The (setf gtk:cell-view-displayed-row) function sets the row of the model that is currently displayed by the cell view. If the path is unset, then the contents of the cell view "stick" at their last value. This is not normally a desired result, but may be a needed intermediate state if say, the model for the cell view becomes temporarily empty.
Warning:
The gtk:cell-view implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-20

GtkIconView

GEnum gtk:icon-view-drop-position
Declaration:
(gobject:define-genum "GtkIconViewDropPosition" icon-view-drop-position
  (:export t
   :type-initializer "gtk_icon_view_drop_position_get_type")
  (:no-drop 0)
  (:drop-into 1)
  (:drop-left 2)
  (:drop-right 3)
  (:drop-above 4)
  (:drop-below 5))  
Values:
:no-drop
No drop possible.
:drop-into
Dropped item replaces the item.
:drop-left
Droppped item is inserted to the left.
:drop-right
Dropped item is inserted to the right.
:drop-above
Dropped item is inserted above.
:drop-below
Dropped item is inserted below.
Details:
An enumeration for determining where a dropped item goes.
See also:
2025-3-3
Class gtk:icon-view
Superclasses:
Documented Subclasses:
None
Direct Slots:
activate-on-single-click
The activate-on-single-click property of type :boolean (Read / Write / Construct)
Specifies whether the "item-activated" signal will be emitted after a single click.
Default value: false
cell-area
The cell-area property of type gtk:cell-area (Read / Write / Construct)
The cell area used to layout cell renderers for this icon view. If no area is specified when creating the icon view a gtk:cell-area-box object will be used.
column-spacing
The column-spacing property of type :int (Read / Write)
Specifies the space which is inserted between the columns of the icon view.
Allowed values: >= 0
Default value: 6
columns
The columns property of type :int (Read / Write)
Contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area.
Allowed values: >= -1
Default value: -1
item-orientation
The item-orientation property of type gtk:orientation (Read / Write)
Specifies how the cells, that is the icon and the text, of the item are positioned relative to each other.
Default value: :vertical
item-padding
The item-padding property of type :int (Read / Write)
Specifies the padding around each item of the icon view.
Allowed values: >= 0
Default value: 6
item-width
The item-width property of type :int (Read / Write)
Specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size.
Allowed values: >= -1
Default value: -1
margin
The margin property of type :int (Read / Write)
Specifies the space which is inserted at the edges of the icon view.
Allowed values: >= 0
Default value: 6
markup-column
The markup-column property of type :int (Read / Write)
Contains the number of the model column containing markup information to be displayed. The markup column must be of "gchararray" type. If this property and the text-column property are both set to column numbers, it overrides the text column. If both are set to -1, no texts are displayed.
Allowed values: >= -1
Default value: -1
model
The model property of type gtk:tree-model (Read / Write)
The model for the icon view.
pixbuf-column
The pixbuf-column property of type :int (Read / Write)
Contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of "GdkPixbuf" type. Setting this property to -1 turns off the display of pixbufs.
Allowed values: >= -1
Default value: -1
reorderable
The reorderable property of type :boolean (Read / Write)
The reorderable property specifies if the items can be reordered by drag and drop.
Default value: false
row-spacing
The row-spacing property of type :int (Read / Write)
Specifies the space which is inserted between the rows of the icon view.
Allowed values: >= 0
Default value: 6
selection-mode
The selection-mode property of type gtk:selection-mode (Read / Write)
Specifies the selection mode of an icon view. If the mode is :multiple, rubberband selection is enabled, for the other modes, only keyboard selection is possible.
Default value: :single
spacing
The spacing property of type :int (Read / Write)
Specifies the space which is inserted between the cells, that is the icon and the text, of an item.
Allowed values: >= 0
Default value: 0
text-column
The text-column property of type :int (Read / Write)
Contains the number of the model column containing the texts which are displayed. The text column must be of "gchararray" type. If this property and the markup-column property are both set to -1, no texts are displayed.
Allowed values: >= -1
Default value: -1
tooltip-column
The tooltip-column property of type :int (Read / Write)
The column in the model containing the tooltip texts for the items.
Allowed values: >= -1
Default value: -1
Returned by:
Slot Access Functions:
Details:
The gtk:icon-view widget provides an alternative view on a gtk:tree-model object. It displays the model as a grid of icons with labels. Like the gtk:tree-view widget, it allows to select one or multiple items, depending on the selection mode, see the gtk:icon-view-selection-mode function. In addition to selection with the arrow keys, the gtk:icon-view class supports rubberband selection, which is controlled by dragging the pointer.

Figure: GtkIconView

Note that if the tree model is backed by an actual tree store, as opposed to a flat list where the mapping to icons is obvious, the gtk:icon-view widget will only display the first level of the tree and ignore the tree's branches.
CSS nodes:
The gtk:icon-view implementation has a single CSS node with name iconview and .view style class. For rubberband selection, a subnode with name rubberband is used.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
Signal Details:
The "activate-cursor-item" signal
lambda (view)    :action      
view
The gtk:icon-view widget on which the signal is emitted.
A keybinding signal which gets emitted when the user activates the currently focused item. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control activation programmatically. The default bindings for this signal are the Space, Return and Enter keys.
The "item-activated" signal
lambda (view path)    :run-last      
view
The gtk:icon-view widget on which the signal is emitted.
path
The gtk:tree-path instance for the activated item.
The signal is emitted when the gtk:icon-view-item-activated function is called or the user double clicks an item. It is also emitted when a non-editable item is selected and one of the Space, Return or Enter keys is pressed.
The "move-cursor" signal
lambda (view step count extent modify)    :action      
view
The gtk:icon-view widget which received the signal.
step
The granularity of the move, as a value of the gtk:movement-step enumeration.
count
The integer with the number of step units to move.
extend
The boolean whether to extend the selection.
modify
The boolean whether to modify the selection.
The signal is a keybinding signal which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal include
  • Arrow keys which move by individual steps.
  • Home/End keys which move to the first/last item.
  • PageUp/PageDown which move by "pages".
All of these will extend the selection when combined with the Shift modifier.
The "select-all" signal
lambda (view)    :action      
view
The gtk:icon-view widget on which the signal is emitted.
A keybinding signal which gets emitted when the user selects all items. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control selection programmatically. The default binding for this signal is the Ctrl-a key.
The "select-cursor-item" signal
lambda (view)    :action      
view
The gtk:icon-view widget on which the signal is emitted.
A keybinding signal which gets emitted when the user selects the item that is currently focused. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control selection programmatically. There is no default binding for this signal.
The "selection-changed" signal
lambda (view)    :run-first     
view
The gtk:icon-view widget on which the signal is emitted.
The signal is emitted when the selection changes, that is the set of selected items.
The "toggle-cursor-item" signal
lambda (view)    :action      
view
The gtk:icon-view widget on which the signal is emitted.
A keybinding signal which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control selection programmatically. The default binding for this signal is the Ctrl-Space key.
The "unselect-all" signal
lambda (view)    :action      
view
The gtk:icon-view widget on which the signal is emitted.
A keybinding signal which gets emitted when the user unselects all items. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control selection programmatically. The default binding for this signal is the Ctrl-Shift-a key.
See also:
2025-3-3
Accessor gtk:icon-view-activate-on-single-click (object)
Syntax:
(gtk:icon-view-activate-on-single-click object) => setting
(setf (gtk:icon-view-activate-on-single-click object) setting)
Arguments:
object -- a gtk:icon-view widget
setting -- a boolean that is true to emit the "item-activated" signal on a single click
Details:
Accessor of the activate-on-single-click slot of the gtk:icon-view class. Causes the "item-activated" signal to be emitted on a single click instead of a double click.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-cell-area (object)
Syntax:
(gtk:icon-view-cell-area object) => area
Arguments:
object -- a gtk:icon-view widget
area -- a gtk:cell-area object used to layout cell renderers
Details:
Accessor of the cell-area slot of the gtk:icon-view class. The gtk:cell-area object used to layout cell renderers for this view. If no area is specified when creating the icon view with the gtk:icon-view-new-with-area function a gtk:cell-area-box object will be used.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-column-spacing (object)
Syntax:
(gtk:icon-view-column-spacing object) => spacing
(setf (gtk:icon-view-column-spacing object) spacing)
Arguments:
object -- a gtk:icon-view widget
spacing -- an integer for the column spacing
Details:
Accessor of the column-spacing slot of the gtk:icon-view class. Specifies the space which is inserted between the columns of the icon view.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-columns (object)
Syntax:
(gtk:icon-view-columns object) => columns
(setf (gtk:icon-view-columns object) columns)
Arguments:
object -- a gtk:icon-view widget
columns -- an integer for the number of columns
Details:
Accessor of the columns slot of the gtk:icon-view class. Determines in how many columns the icons are arranged. If columns is -1, the number of columns will be chosen automatically to fill the available area.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-item-orientation (object)
Syntax:
(gtk:icon-view-item-orientation object) => orientation
(setf (gtk:icon-view-item-orientation object) orientation)
Arguments:
object -- a gtk:icon-view widget
orientation -- a gtk:orientation value for the relative position of texts and icons
Details:
Accessor of the item-orientation slot of the gtk:icon-view class. Determines whether the labels are drawn beside the icons instead of below.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-item-padding (object)
Syntax:
(gtk:icon-view-item-padding object) => padding
(setf (gtk:icon-view-item-padding object) padding)
Arguments:
object -- a gtk:icon-view widget
padding -- an integer for the item padding
Details:
Accessor of the item-padding slot of the gtk:icon-view class. Specifies the padding around each of the icon view's items.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-item-width (object)
Syntax:
(gtk:icon-view-item-width object) => width
(setf (gtk:icon-view-item-width object) width)
Arguments:
object -- a gtk:icon-view widget
width -- an integer for the width for each item
Details:
Accessor of the item-width slot of the gtk:icon-view class. Specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-margin (object)
Syntax:
(gtk:icon-view-margin object) => margin
(setf (gtk:icon-view-margin object) margin)
Arguments:
object -- a gtk:icon-view widget
margin -- an integer for the margin
Details:
Accessor of the margin slot of the gtk:icon-view class. Specifies the space which is inserted at the top, bottom, left and right of the icon view.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-markup-column (object)
Syntax:
(gtk:icon-view-markup-column object) => column
(setf (gtk:icon-view-markup-column object) column)
Arguments:
object -- a gtk:icon-view widget
column -- an integer for a column in the currently used model, or -1 to display no text
Details:
Accessor of the markup-column slot of the gtk:icon-view class. The gtk:icon-view-markup-column function returns the column with markup text for the icon view. The (setf gtk:icon-view-markup-column) function sets the column with markup information.

The markup column must be of "gchararray" type. If the markup column is set to something, it overrides the text column set by the gtk:icon-view-text-column function.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-model (object)
Syntax:
(gtk:icon-view-model object) => model
(setf (gtk:icon-view-model object) model)
Arguments:
object -- a gtk:icon-view widget
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:icon-view class. The gtk:icon-view-model function returns the model the gtk:icon-view widget is based on. Returns nil if the model is unset. The (setf gtk:icon-view-model) function sets the model.

If the icon view already has a model set, it will remove it before setting the new model. If model is nil, then it will unset the old model.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-pixbuf-column (object)
Syntax:
(gtk:icon-view-pixbuf-column object) => column
(setf (gtk:icon-view-pixbuf-column object) column)
Arguments:
object -- a gtk:icon-view widget
column -- an integer for a column in the currently used model, or -1 to disable
Details:
Accessor of the pixbuf-column slot of the gtk:icon-view class. The gtk:icon-view-pixbuf-column function returns the column with pixbufs for the icon view. The (setf gtk:icon-view-pixbuf-column) function sets the column with pixbufs.

The pixbuf column must be of "GdkPixbuf" type.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-reorderable (object)
Syntax:
(gtk:icon-view-reorderable object) => reorderable
(setf (gtk:icon-view-reorderable object) reorderable)
Arguments:
object -- a gtk:icon-view widget
reorderable -- true, if the list of items can be reordered
Details:
Accessor of the reorderable slot of the gtk:icon-view class. The gtk:icon-view-reorderable function retrieves whether the user can reorder the list via drag and drop. The (setf gtk:icon-view-reorderable) function sets whether the user can reorder the list. This function is a convenience function to allow you to reorder models that support the gtk:tree-drag-source and the gtk:tree-drag-dest interfaces.

Both gtk:tree-store and gtk:list-store objects support these. If reorderable is true, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's "row-inserted" and "row-deleted" signals. The reordering is implemented by setting up the icon view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose.

This function does not give you any degree of control over the order - any reordering is allowed. If more control is needed, you should probably handle drag and drop manually.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-row-spacing (object)
Syntax:
(gtk:icon-view-row-spacing object) => spacing
(setf (gtk:icon-view-row-spacing object) spacing)
Arguments:
object -- a gtk:icon-view widget
spacing -- an integer for the row spacing
Details:
Accessor of the row-spacing slot of the gtk:icon-view class. Specifies the space which is inserted between the rows of the icon view.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-selection-mode (object)
Syntax:
(gtk:icon-view-selection-mode object) => mode
(setf (gtk:icon-view-selection-mode object) mode)
Arguments:
object -- a gtk:icon-view widget
mode -- a gtk:selection-mode value
Details:
Accessor of the selection-mode slot of the gtk:icon-view class. The gtk:icon-view-selection-mode function gets the selection mode of the icon view. The (setf gtk:icon-view-selection-mode) function sets the selection mode.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-spacing (object)
Syntax:
(gtk:icon-view-spacing object) => spacing
(setf (gtk:icon-view-spacing object) spacing)
Arguments:
object -- a gtk:icon-view widget
spacing -- an integer for the spacing
Details:
Accessor of the spacing slot of the gtk:icon-view class. Specifies the space which is inserted between the cells, that is the icon and the text, of an item.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-text-column (object)
Syntax:
(gtk:icon-view-text-column object) => column
(setf (gtk:icon-view-text-column object) column)
Arguments:
object -- a gtk:icon-view widget
column -- an integer for a column in the currently used model, or -1 to display no text
Details:
Accessor of the text-column slot of the gtk:icon-view class. The gtk:icon-view-text-column function returns the column with text for the icon view. The (setf gtk:icon-view-text-column) function sets the column. The text column must be of "gchararray" type.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Accessor gtk:icon-view-tooltip-column (object)
Syntax:
(gtk:icon-view-tooltip-column object) => column
(setf (gtk:icon-view-tooltip-column object) column)
Arguments:
object -- a gtk:icon-view widget
column -- an integer, which is a valid column number
Details:
Accessor of the tooltip-column slot of the gtk:icon-view class. The gtk:icon-view-tooltip-column function returns the column of the icon view's model which is being used for displaying tooltips on the icon view's rows. The (setf gtk:icon-view-tooltip-column) function sets the column.

If you only plan to have simple (text-only) tooltips on full items, you can use this function to have the gtk:icon-view widget handle these automatically for you. The column argument should be set to the column in the icon view's model containing the tooltip texts, or -1 to disable this feature.

When enabled, the has-tooltip property will be set to true and the icon view will connect a "query-tooltip" signal handler. Note that the signal handler sets the text with the gtk:tooltip-set-markup function, so &, <, etc have to be escaped in the text.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
2025-3-3
Function gtk:icon-view-new ()
Returns:
The newly created gtk:icon-view widget.
Details:
Creates a new icon view.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-new-with-area (area)
Arguments:
area -- a gtk:cell-area object to use to layout cells
Returns:
The newly created gtk:icon-view widget.
Details:
Creates a new icon view using the specified area to layout cells inside the icons.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-new-with-model (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The newly created gtk:icon-view widget.
Details:
Creates a new icon view with the model model.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-path-at-pos (view x y)
Arguments:
view -- a gtk:icon-view widget
x -- an integer for the x position to be identified
y -- an integer for the y position to be identified
Returns:
The gtk:tree-path instance corresponding to the icon or nil if no icon exists at that position.
Details:
Gets the path for the icon at the given position.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-item-at-pos (view x y)
Arguments:
view -- a gtk:icon-view widget
x -- an integer for the x position to be identified
y -- an integer for the y position to be identified
Returns:
path -- a gtk:tree-path instance, or nil
cell -- a gtk:cell-renderer object responsible for the cell at (x,y), or nil if no item exists at the specified position
Details:
Gets the path and cell for the icon at the given position.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-set-cursor (view path cell start)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance
cell -- one of the gtk:cell-renderer objects of view, or nil
start -- true if the specified cell should start being edited
Details:
Sets the current keyboard focus to be at path, and selects it. This is useful when you want to focus the user's attention on a particular item. If cell is not nil, then focus is given to the cell specified by it. Additionally, if start is true, then editing should be started in the specified cell.

This function is often followed by a call of the gtk:widget-grab-focus function in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-get-cursor (view)
Arguments:
view -- a gtk:icon-view widget
Returns:
path -- a current gtk:tree-path cursor path, or nil
cell -- a current gtk:cell-renderer focus cell, or nil if the cursor is not set
Details:
Returns the current cursor path and focus cell. If the cursor is not currently set, then path will be nil. If no cell currently has focus, then cell will be nil.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Callback gtk:icon-view-foreach-func
Syntax:
lambda (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance of a selected row
Details:
A callback function used by the gtk:icon-view-selected-foreach function to map all selected rows. It will be called on every selected row in the view.
See also:
#2025-3-3
Function gtk:icon-view-selected-foreach (view func)
Arguments:
view -- a gtk:icon-view widget
func -- a gtk:icon-view-foreach-func callback function to call for each selected icon
Details:
Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-cell-rect (view path cell)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance
cell -- a gtk:cell-renderer object or nil
Returns:
The gdk:rectangle instance with the cell rectangle or nil.
Details:
Returns the bounding rectangle in widget coordinates for the cell specified by path and cell. If cell is nil the main cell area is used. This function is only valid if view is realized.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-select-path (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance to be selected
Details:
Selects the row at path.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-unselect-path (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance to be unselected
Details:
Unselects the row at path.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-path-is-selected (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance to check selection on
Returns:
True if path is selected.
Details:
Returns true if the icon pointed to by path is currently selected. If path does not point to a valid location, nil is returned.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-selected-items (view)
Arguments:
view -- a gtk:icon-view widget
Returns:
The list containing a gtk:tree-path instance for each selected row.
Details:
Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of gtk:tree-row-reference instances. To do this, you can use the gtk:tree-row-reference-new function.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-select-all (view)
Arguments:
view -- a gtk:icon-view widget
Details:
Selects all the icons. The icon view must have its selection mode set to the value :multiple of the gtk:selection-mode enumeration.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-unselect-all (view)
Arguments:
view -- a gtk:icon-view widget
Details:
Unselects all the icons.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-item-activated (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance to be activated
Details:
Activates the item determined by path.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-scroll-to-path (view path &key row-align col-align)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance for the item to move to
row-align -- a number coerced to a single float for the vertical alignment of the item specified by path
col-align -- a number coerced to a single float for the horizontal alignment of the item specified by path
Details:
Moves the alignments of view to the position specified by path. The row-align argument determines where the row is placed, and the col-align argument determines where the column is placed. Both are expected to be between 0.0 and 1.0. The 0.0 value means left/top alignment, the 1.0 value means right/bottom alignment, the 0.5 value means center. The keyword arguments have the default 0.5 value.

If both row-align and col-align arguments are nil, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to its current position. If the item is currently visible on the screen, nothing is done.

This function only works if the model is set, and path is a valid row on the model. If the model changes before the view is realized, the centered path will be modified to reflect this change.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-visible-range (view)
Arguments:
view -- a gtk:icon-view widget
Returns:
start -- a gtk:tree-path instance with the start of the region, or nil
end -- a gtk:tree-path instance with the end of the region, or nil
Details:
Returns start and end to be the first and last visible path. Returns nil if valid paths were not returned in start and end. Note that there may be invisible paths in between.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-set-tooltip-item (view tooltip path)
Arguments:
view -- a gtk:icon-view widget
tooltip -- a gtk:tooltip object
path -- a gtk:tree-path instance
Details:
Sets the tip area of tooltip to be the area covered by the item at path. See also the gtk:icon-view-tooltip-column function for a simpler alternative. See also the gtk:tooltip-set-tip-area function.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-set-tooltip-cell (view tooltip path cell)
Arguments:
view -- a gtk:icon-view widget
tooltip -- a gtk:tooltip object
path -- a gtk:tree-path instance
cell -- a gtk:cell-renderer object or nil
Details:
Sets the tip area of the tooltip to the area which cell occupies in the item pointed to by path. See also the gtk:tooltip-set-tip-area function. See also the gtk:icon-view-tooltip-column function for a simpler alternative.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-tooltip-context (view x y tip)
Arguments:
view -- a gtk:icon-view widget
x -- an integer for the x coordinate, relative to widget coordinates
y -- an integer for the y coordinate, relative to widget coordinates
tip -- a boolean whether this is a keyboard tooltip or not
Returns:
xx -- an integer with x converted to be relative to the bin window of view
yy -- an integer with y converted to be relative to the bin window of view
model -- a gtk:tree-model object or nil
path -- a gtk:tree-path instance or nil
iter -- a gtk:tree-iter iterator or nil
Details:
This function is supposed to be used in a "query-tooltip" signal handler for a gtk:icon-view widget. The x, y and tip values which are received in the signal handler, should be passed to this function without modification.

The return value indicates whether there is an icon view item at the given coordinates, true) or not false for mouse tooltips. For keyboard tooltips the item returned will be the cursor item. When true, then any of model, path and iter will be set to point to that row and the corresponding model. x and y will always be converted to be relative to the bin window of view if tip is false.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-item-row (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance of the item
Returns:
The integer with the row in which the item is displayed.
Details:
Gets the row in which the item path is currently displayed. Row numbers start at 0.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-item-column (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance of the item
Returns:
The integer with the column in which the item is displayed.
Details:
Gets the column in which the item path is currently displayed. Column numbers start at 0.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-enable-model-drag-source (view mask formats actions)
Arguments:
view -- a gtk:icon-view widget
mask -- a gdk:modifier-type value for the allowed buttons to start drag
formats -- a gdk:content-formats instance for the formats that the drag will support
actions -- a gdk:drag-action value for the possible actions for a drag from this widget
Details:
Turns the icon view into a drag source for automatic DND. Calling this method sets the reorderable property to the false value.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-enable-model-drag-dest (view formats actions)
Arguments:
view -- a gtk:icon-view widget
formats -- a gdk:content-formats instance for the formats that the drag will support
actions -- a gdk:drag-action value for the possible actions for a drag to this widget
Details:
Turns the icon view into a drop destination for automatic drag and drop. Calling this method sets the reorderable property to the false value.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-unset-model-drag-source (view)
Arguments:
view -- a gtk:icon-view widget
Details:
Undoes the effect of the gtk:icon-view-enable-model-drag-source function. Calling this method sets the reorderable property to false.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-unset-model-drag-dest (view)
Arguments:
view -- a gtk:icon-view widget
Details:
Undoes the effect of the gtk:icon-view-enable-model-drag-dest function. Calling this method sets the reorderable property to false.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-set-drag-dest-item (view path pos)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance of the item to highlight, or nil
pos -- a gtk:icon-view-drop-position value which specifies where to drop, relative to the item
Details:
Sets the item that is highlighted for feedback.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-get-drag-dest-item (view)
Arguments:
view -- a gtk:icon-view widget
Returns:
path -- a gtk:tree-path instance for the highlighted item, or nil
pos -- a gtk:icon-view-drop-position value with the drop position, or nil
Details:
Gets information about the item that is highlighted for feedback.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-dest-item-at-pos (view xdrag ydrag)
Arguments:
view -- a gtk:icon-view widget
xdrag -- an integer for the position to determine the destination item for
ydrag -- an integer for the position to determine the destination item for
Returns:
path -- a gtk:tree-path instance for the item
pos -- a gtk:icon-view-drop-position value
Details:
Determines the destination item for a given position.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3
Function gtk:icon-view-create-drag-icon (view path)
Arguments:
view -- a gtk:icon-view widget
path -- a gtk:tree-path instance
Returns:
The newly allocated cairo:surface-t surface for the drag icon.
Details:
Creates a cairo:surface-t representation of the item at path. This image is used for a drag icon.
Warning:
The gtk:icon-view implementation is deprecated since 4.10. Use the gtk:grid-view implementation instead.
See also:
#2025-3-3

GtkTreeSortable

Constant gtk:+tree-sortable-default-sort-column-id+
Initial Value:
-1
Details:
The default sort column ID can be used to make a gtk:tree-sortable object use the default sort function. See also the gtk:tree-sortable-sort-column-id function.
See also:
2024-5-9
Constant gtk:+tree-sortable-unsorted-sort-column-id+
Initial Value:
-2
Details:
The unsorted sort column ID can be used to make a gtk:tree-sortable object use no sorting. See also the gtk:tree-sortable-sort-column-id function.
See also:
2024-5-9
Interface gtk:tree-sortable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gtk:tree-sortable interface is an interface to be implemented by tree models which support sorting. The gtk:tree-view widget uses the methods provided by this interface to sort the model.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. There is no replacement for this interface. You should use the gtk:sort-list-model implementation to wrap your list model instead.
Signal Details:
The "sort-column-changed" signal
 lambda (sortable)    : Run Last      
sortable
The gtk:tree-sortable object on which the signal is emitted.
The signal is emitted when the sort column or sort order of sortable is changed. The signal is emitted before the contents of sortable are resorted.
See also:
2024-5-9
Function gtk:tree-sortable-sort-column-changed (sortable)
Arguments:
sortable -- a gtk:tree-sortable object
Details:
Emits a "sort-column-changed" signal on sortable.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-9
Function gtk:tree-sortable-sort-column-id (sortable)
Syntax:
(gtk:tree-sortable-sort-column-id sortable) => column, order
(setf (gtk:tree-sortable-sort-column-id sortable) column)
(setf (gtk:tree-sortable-sort-column-id sortable) '(column order))
Arguments:
sortable -- a gtk:tree-sortable object
column -- an integer with the sort column ID
order -- a value of the gtk:sort-type enumeration
Details:
The gtk:tree-sortable-sort-column-id function returns the current sort column ID and the sort order. The (setf gtk:tree-sortable-sort-column-id) function sets the sort column ID and the sort order. If no sort order is given, the sort order is set to the default value :ascending.

The sortable will resort itself to reflect this change, after emitting a "sort-column-changed" signal. The column argument may either be a regular column ID, or one of the following special values: gtk:+tree-sortable-default-sort-column-id+ or gtk:+tree-sortable-unsorted-sort-column-id+.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-9
Callback gtk:tree-iter-compare-func
Syntax:
lambda (model iter1 iter2) => result
Arguments:
model -- a gtk:tree-model object the comparison is within
iter1 -- a gtk:tree-iter iterator in model
iter2 -- another gtk:tree-iter iterator in model
result -- a negative integer, zero or a positive integer depending on whether iter1 sorts before, with or after iter2
Details:
The gtk:tree-iter-compare-func callback function should return a negative integer, zero, or a positive integer if iter1 sorts before iter2, iter1 sorts with iter2, or iter1 sorts after iter2 respectively. If two iterators compare as equal, their order in the sorted model is undefined. To ensure that the gtk:tree-sortable object behaves as expected, the gtk:tree-iter-compare-func callback function must define a partial order on the model, that is, it must be reflexive, antisymmetric and transitive.
See also:
#2024-5-9
Function gtk:tree-sortable-set-sort-func (sortable column func)
Arguments:
sortable -- a gtk:tree-sortable object
column -- an integer with the sort column ID to set the function for
func -- a gtk:tree-iter-compare-func callback function
Details:
Sets the comparison function used when sorting to be func. If the current sort column ID of sortable is the same as column, then the model will sort using this function.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-9
Function gtk:tree-sortable-set-default-sort-func (sortable func)
Arguments:
sortable -- a gtk:tree-sortable object
func -- a gtk:tree-iter-compare-func callback function
Details:
Sets the default comparison callback function used when sorting to be func. If the current sort column ID of sortable is gtk:+tree-sortable-default-sort-column-id+, then the model will sort using this function.

If func is nil, then there will be no default comparison function. This means that once the model has been sorted, it cannot go back to the default state. In this case, when the current sort column ID of sortable is gtk:+tree-sortable-default-sort-column-id+, the model will be unsorted.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-9
Function gtk:tree-sortable-has-default-sort-func (sortable)
Arguments:
sortable -- a gtk:tree-sortable object
Returns:
True, if the model has a default sort function.
Details:
Returns true if the model has a default sort function. This is used primarily by gtk:tree-view-column objects in order to determine if a model can go back to the default state, or not.
Warning:
The gtk:tree-sortable implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-5-9

GtkTreeModelSort

Class gtk:tree-model-sort
Superclasses:
gtk:tree-model, gtk:tree-sortable, gtk:tree-drag-source, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
model
The model property of type gtk:tree-model (Read / Write / Construct)
The model to sort.
Returned by:
Slot Access Functions:
Details:
The gtk:tree-model-sort object is a model which implements the gtk:tree-sortable interface. It does not hold any data itself, but rather is created with a child model and proxies its data. It has identical column types to this child model, and the changes in the child are propagated. The primary purpose of this model is to provide a way to sort a different model without modifying it. Note that the sort function used by the gtk:tree-model-sort object is not guaranteed to be stable.
Examples:
The use of this is best demonstrated through an example. In the following sample code we create two gtk:tree-view widgets each with a view of the same data. As the model is wrapped here by a gtk:tree-model-sort object, the two gtk:tree-view widgets can each sort their view of the data without affecting the other. By contrast, if we simply put the same model in each widget, then sorting the first would sort the second.
(let* (;; Get the child model
       (child-model (gtk:my-model()))
       ;; Create the first tree view
       (sort-model1 (gtk:tree-model-sort-new-with-model child-model))
       (tree-view1 (gtk:tree-view-with-model sort-model1))
       ;; Create the second tree view
       (sort-model2 (gtk:tree-vmodel-sort-new-with-model child-model))
       (tree-view2 (gtk:tree-view-new-with-model sort-model2)))
  ;; Now we can sort the two models independently
  (setf (gtk:tree-sortable-sort-column-id sort-model1) col1)
  (setf (gtk:tree-sortable-sort-column-id sort-model1) '(col1 :descending))
  ... )    
To demonstrate how to access the underlying child model from the sort model, the next example will be a callback for the "changed" signal of the gtk:tree-selection object. In this callback, we get a string from col1 of the model. We then modify the string, find the same selected row on the child model, and change the row there.
(defun selection-changed (selection)
  (let* ((view (gtk:tree-selection-tree-view selection))
         ;; Get the current selected row and the model
         (sort-model (gtk:tree-view-model view))
         (sort-iter (gtk:tree-selection-selected selection))
         ;; Look up the current value on the selected row and get a new value
         (value (gtk:tree-model-value sort-model sort-iter col1))
         (new-value (change-the-value value))
         ;; Get the child model and an iterator on the child model
         (model (gtk:tree-model-sort-model sort-model))
         (iter (gtk:tree-model-sort-convert-iter-to-child-iter sort-model
                                                               sort-iter)))
    ;; Change the value of the row in the child model
    (gtk:list-store-set-value model iter col1 new-value)))    
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
2024-5-9
Accessor gtk:tree-model-sort-model (object)
Syntax:
(gtk:tree-model-sort-model object) => model
Arguments:
object -- a gtk:tree-model-sort object
model -- a gtk:tree-model child model being sorted
Details:
Accessor of the model slot of the gtk:tree-model-sort class. The gtk:tree-model-sort-model function returns the model the gtk:tree-model-sort object is sorting.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
2024-5-9
Function gtk:tree-model-sort-new-with-model (model)
Arguments:
model -- a gtk:tree-model object, or nil
Returns:
The new gtk:tree-model object.
Details:
Creates a new tree model, with model as the child model.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
2024-5-9
Function gtk:tree-model-sort-convert-child-path-to-path (model path)
Arguments:
model -- a gtk:tree-model-sort object
path -- a gtk:tree-path instance to convert
Returns:
The gtk:tree-path instance, or nil.
Details:
Converts path to a path relative to model. That is, path points to a path in the child model. The returned path will point to the same row in the sorted model. If path is not a valid path on the child model, then nil is returned.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9
Function gtk:tree-model-sort-convert-child-iter-to-iter (model iter)
Arguments:
model -- a gtk:tree-model-sort object
iter -- a valid gtk:tree-iter instance pointing to a row on the child model
Returns:
The valid gtk:tree-iter iterator to a visible row in the sorted model, or nil.
Details:
Returns the iterator to the row in model that corresponds to the row pointed at by iter.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9
Function gtk:tree-model-sort-convert-path-to-child-path (model path)
Arguments:
model -- a gtk:tree-model-sort object
path -- a gtk:tree-path instance to convert
Returns:
The gtk:tree-path instance, or nil.
Details:
Converts path to a path on the child model of model. That is, path points to a location in model. The returned path will point to the same location in the model not being sorted. If path does not point to a location in the child model, nil is returned.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9
Function gtk:tree-model-sort-convert-iter-to-child-iter (model iter)
Arguments:
model -- a gtk:tree-model-sort object
iter -- a valid gtk:tree-iter iterator pointing to a row on model
Returns:
The gtk:tree-iter iterator.
Details:
Converts iter to point to a row on model.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9
Function gtk:tree-model-sort-reset-default-sort-func (model)
Arguments:
model -- a gtk:tree-model-sort object
Details:
This resets the default sort function to be in the 'unsorted' state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the gtk:tree-model-sort object is in 'unsorted' state.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9
Function gtk:tree-model-sort-iter-is-valid (model iter)
Arguments:
model -- a gtk:tree-model-sort object
iter -- a gtk:tree-iter iterator
Returns:
True if iter is valid, nil if iter is invalid.
Details:
Checks if the given iter is a valid iterator for this gtk:tree-model-sort object.
Notes:
This function is slow. Only use it for debugging and/or testing purposes.
Warning:
The gtk:tree-model-sort implementation is deprecated since 4.10. Use the gtk:sort-list-model implementation instead.
See also:
#2024-5-9

GtkTreeModelFilter

Class gtk:tree-model-filter
Superclasses:
gtk:tree-model, gtk:tree-drag-source, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
child-model
The child-model property of type gtk:tree-model (Read / Write / Construct)
The model for the filter model to filter.
virtual-root
The virtual-root property of type gtk:tree-path (Read / Write / Construct)
The virtual root, relative to the child model, for this filter model.
Returned by:
Slot Access Functions:
Details:
The gtk:tree-model-filter object is a tree model which wraps another tree model. It can do the following things:
  • Filter specific rows, based on data from a "visible column", a column storing booleans indicating whether the row should be filtered or not, or based on the return value of a "visible function", which gets a model, iterator and returns a boolean indicating whether the row should be filtered or not.
  • Modify the "appearance" of the model, using a modify function. This is extremely powerful and allows for just changing some values and also for creating a completely different model based on the given child model.
  • Set a different root node, also known as a "virtual root". You can pass in a gtk:tree-path instance indicating the root node for the filter at construction time.
The basic API is similar to the gtk:tree-model-sort class. For an example on its usage, see the gtk:tree-model-sort documentation.

When using the gtk:tree-model-filter object, it is important to realize that the gtk:tree-model-filter object maintains an internal cache of all nodes which are visible in its clients. The cache is likely to be a subtree of the tree exposed by the child model. The gtk:tree-model-filter object will not cache the entire child model when unnecessary to not compromise the caching mechanism that is exposed by the reference counting scheme. If the child model implements reference counting, unnecessary signals may not be emitted because of reference counting, see the gtk:tree-model documentation. Note that, for example; the gtk:tree-store object does not implement reference counting and will always emit all signals, even when the receiving node is not visible.

Because of this, limitations for possible visible functions do apply. In general, visible functions should only use data or properties from the node for which the visibility state must be determined, its siblings or its parents. Usually, having a dependency on the state of any child node is not possible, unless references are taken on these explicitly. When no such reference exists, no signals may be received for these child nodes. See reference counting in the gtk:tree-model documentation.

Determining the visibility state of a given node based on the state of its child nodes is a frequently occurring use case. Therefore, the gtk:tree-model-filter object explicitly supports this. For example, when a node does not have any children, you might not want the node to be visible. As soon as the first row is added to the node's child level, or the last row removed, the node's visibility should be updated.

This introduces a dependency from the node on its child nodes. In order to accommodate this, the gtk:tree-model-filter object must make sure the necesary signals are received from the child model. This is achieved by building, for all nodes which are exposed as visible nodes to the gtk:tree-model-filter objects clients, the child level (if any) and take a reference on the first node in this level. Furthermore, for every "row-inserted", "row-changed" or "row-deleted" signal, also these which were not handled because the node was not cached, the gtk:tree-model-filter object will check if the visibility state of any parent node has changed.

Beware, however, that this explicit support is limited to these two cases. For example, if you want a node to be visible only if two nodes in a child's child level (2 levels deeper) are visible, you are on your own. In this case, either rely on the gtk:tree-store object to emit all signals because it does not implement reference counting, or for models that do implement reference counting, obtain references on these child levels yourself.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
2024-4-29
Accessor gtk:tree-model-filter-child-model (object)
Syntax:
(gtk:tree-model-filter-child-model object) => child
Arguments:
object -- a gtk:tree-model-filter object
child -- a gtk:tree-model object
Details:
Accessor of the child-model slot of the gtk:tree-model-filter class. The model for the filter model to filter.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
2024-4-29
Accessor gtk:tree-model-filter-virtual-root (object)
Syntax:
(gtk:tree-model-filter-virtual-root object) => root
Arguments:
object -- a gtk:tree-model-filter object
root -- a gtk:tree-path instance
Details:
Accessor of the virtual-root slot of the gtk:tree-model-filter class. The virtual root, relative to the child model, for this filter model.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
2024-4-29
Function gtk:tree-model-filter-new (child root)
Arguments:
child -- a gtk:tree-model object
root -- a gtk:tree-path instance or nil
Returns:
The new gtk:tree-model object.
Details:
Creates a new gtk:tree-model object, with child as the child model and root as the virtual root.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
2024-12-24
Callback gtk:tree-model-filter-visible-func
Syntax:
lambda (model iter) => result
Arguments:
model -- a child model of the gtk:tree-model-filter object
iter -- a gtk:tree-iter iterator pointing to the row in model whose visibility is determined
result -- a boolean whether the row indicated by iter is visible
Details:
A callback function which decides whether the row indicated by iter is visible.
See also:
#2024-5-3
Function gtk:tree-model-filter-set-visible-func (filter func)
Arguments:
filter -- a gtk:tree-model-filter object
func -- a gtk:tree-model-filter-visible-func callback function
Details:
Sets the visible function used when filtering the filter model to be func. The function should return true if the given row should be visible and false otherwise.

If the condition calculated by the function changes over time, for example, because it depends on some global parameters, you must call the gtk:tree-model-filter-refilter function to keep the visibility information of the model uptodate.

Note that func is called whenever a row is inserted, when it may still be empty. The visible function should therefore take special care of empty rows.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Callback gtk:tree-model-filter-modify-func
Syntax:
lambda (model iter value column)
Arguments:
model -- a gtk:tree-model-filter object
iter -- a gtk:tree-iter iterator pointing to the row whose display values are determined
value -- a g:value instance which is already initialized for with the correct type for the column column
column -- an integer with the column whose display value is determined
Details:
A callback function which calculates display values from raw values in the model. It must fill value with the display value for the column column in the row indicated by iter.

Since this function is called for each data access, it is not a particularly efficient operation.
See also:
#2024-5-3
Function gtk:tree-model-filter-set-modify-func (filter gtypes func)
Arguments:
filter -- a gtk:tree-model-filter object
gtypes -- a list of g:type-t type IDs of the columns
func -- a gtk:tree-model-filter-modify-func callback function
Details:
With types parameters, you give a list of column types for this model, which will be exposed to the parent model/view. The func parameter specifies the modify function. The modify function will get called for each data access, the goal of the modify function is to return the data which should be displayed at the location specified using the parameters of the modify function.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-set-visible-column (filter column)
Arguments:
filter -- a gtk:tree-model-filter object
column -- an integer which is the column containing the visible information
Details:
Sets column of the child model to be the column where filter should look for visibility information. The column should be of type "gboolean", where true means that a row is visible, and false if not.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-model (filter)
Arguments:
filter -- a gtk:tree-model-filter object
Returns:
The gtk:tree-model object for the child model.
Details:
Returns the child model of the filter model.
Notes:
This function duplicates the gtk:tree-model-filter-child-model function.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-convert-child-iter-to-iter (filter iter)
Arguments:
filter -- a gtk:tree-model-filter object
iter -- a valid gtk:tree-iter iterator pointing to a row on the child model
Returns:
The gtk:tree-iter iterator in filter if iter is a valid iterator pointing to a visible row in the child model.
Details:
Returns an interator to point to the row in filter that corresponds to the row pointed at by iter. If the iterator was not set, nil is returned.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-convert-iter-to-child-iter (filter iter)
Arguments:
filter -- a gtk:tree-model-filter object
iter -- a valid gtk:tree-iter iterator pointing to a row on filter
Returns:
The gtk:tree-iter iterator.
Details:
Returns the iterator to point to the row pointed to by iter.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-convert-child-path-to-path (filter path)
Arguments:
filter -- a gtk:tree-model-filter object
path -- a gtk:tree-path instance to convert
Returns:
The newly allocated gtk:tree-path instance, or nil.
Details:
Converts path to a path relative to filter. That is, path points to a path in the child model. The returned path will point to the same row in the filtered model. If path is not a valid path on the child model or points to a row which is not visible in filter, then nil is returned.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-convert-path-to-child-path (filter path)
Arguments:
filter -- a gtk:tree-model-filter object
path -- a gtk:tree-path instance to convert
Returns:
The newly allocated gtk:tree-path instance, or nil.
Details:
Converts path to a path on the child model of filter. That is, path points to a location in filter. The returned path will point to the same location in the model not being filtered. If path does not point to a location in the child model, nil is returned.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29
Function gtk:tree-model-filter-refilter (filter)
Arguments:
filter -- a gtk:tree-model-filter object
Details:
Emits the "row_changed" signal for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not.
Warning:
The gtk:tree-model-filter implementation is deprecated since 4.10. Use the gtk:filter-list-model implementation instead.
See also:
#2024-4-29

GtkCellArea

Class gtk:cell-area
Superclasses:
gobject:initially-unowned, gtk:cell-layout, gtk:buildable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
edit-widget
The edit-widget property of type gtk:cell-editable (Read)
The widget currently editing the edited cell. This property is read-only and only changes as a result of calling the gtk:cell-area-activate-cell function.
edited-cell
The edited-cell property of type gtk:cell-renderer (Read)
The cell in the area that is currently edited. This property is read-only and only changes as a result of calling the gtk:cell-area-activate-cell function.
focus-cell
The focus-cell property of type gtk:cell-renderer (Read / Write)
The cell in the area that currently has focus.
Slot Access Functions:
Details:
The gtk:cell-area class is an abstract class for gtk:cell-layout widgets, also referred to as "layouting widgets", to interface with an arbitrary number of gtk:cell-renderer objects and interact with the user for a given gtk:tree-model row.

The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data.

Usually users do not have to interact with the gtk:cell-area object directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes
As outlined in the gtk:widget geometry management section, GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. The gtk:cell-area object uses the same semantics to calculate the size of an area for an arbitrary number of gtk:tree-model rows.

When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a gtk:tree-view-column object always lines up the areas from top to bottom while a gtk:icon-view widget on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width.

It is also important for areas to maintain some cell alignments with areas rendered for adjacent rows, cells can appear "columnized" inside an area even when the size of cells are different in each row. For this reason the gtk:cell-area object uses a gtk:cell-area-context object to store the alignments and sizes along the way, as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context.

The gtk:cell-area-context object is an opaque object specific to the gtk:cell-area object which created it, see the gtk:cell-area-create-context function. The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation, horizontally or vertically. However, it is important that the same gtk:cell-area-context object which was used to request the sizes for a given gtk:tree-model row be used when rendering or processing events for that row.

In order to request the width of all the rows at the root level of a gtk:tree-model object one would do the following:

Example: Requesting the width of a handful of gtk:tree-model rows
GtkTreeIter iter;
gint        minimum_width;
gint        natural_width;

valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL);

valid = gtk_tree_model_iter_next (model, &iter); } gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);
Note that in this example it is not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying gtk:cell-area-context object and can be consulted at any time.

This can be useful since gtk:cell-layout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The gtk:cell-layout widget in that case would calculate the required width of the rows in an idle or timeout source, see the g:timeout-add function, and when the widget is requested its actual width in get_preferred_width() it can simply consult the width accumulated so far in the gtk:cell-area-context object.

A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like:

Example: A typical get_preferred_width() implementation
static void
foo_get_preferred_width (GtkWidget       *widget,
                         gint            *minimum_size,
                         gint            *natural_size)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;

foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);

gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size); }
In the above example the Foo widget has to make sure that some row sizes have been calculated, the amount of rows that Foo judged was appropriate to request space for in a single timeout iteration, before simply returning the amount of space required by the area via the gtk:cell-area-context object.

Requesting the height for width, or width for height, of an area is a similar task except in this case the gtk:cell-area-context object does not store the data, actually, it does not know how much space the layouting widget plans to allocate it for every row. It is up to the layouting widget to render each row of data with the appropriate height and width which was requested by the gtk:cell-area object.

In order to request the height for width of all the rows at the root level of a gtk:tree-model object one would do the following:

Example: Requesting the height for width of a handful of gtk:tree-model rows
GtkTreeIter iter;
gint        minimum_height;
gint        natural_height;
gint        full_minimum_height = 0;
gint        full_natural_height = 0;

valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_height_for_width (area, context, widget, width, &minimum_height, &natural_height);

if (width_is_for_allocation) cache_row_height (&iter, minimum_height, natural_height);

full_minimum_height += minimum_height; full_natural_height += natural_height;

valid = gtk_tree_model_iter_next (model, &iter); }
Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation.

In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it is only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height, or scrolled window height, in response to a single call to the get_preferred_height_for_width() function. Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the the scrollbar values while more and more height is required for the row heights that are calculated in the background.

Rendering Areas Once area sizes have been aquired at least for the rows in the visible area of the layouting widget they can be rendered at draw() time.

A crude example of how to render all the rows at the root level runs as follows:

Example: Requesting the width of a handful of gtk:tree-model rows
GtkAllocation allocation;
GdkRectangle  cell_area = { 0, };
GtkTreeIter   iter;
gint          minimum_width;
gint          natural_width;

gtk_widget_get_allocation (widget, &allocation); cell_area.width = allocation.width;

valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { cell_area.height = get_cached_height_for_row (&iter);

gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_render (area, context, widget, cr, &cell_area, &cell_area, state_flags, FALSE);

cell_area.y += cell_area.height;

valid = gtk_tree_model_iter_next (model, &iter); }
Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at "size-allocate" time using the gtk_distribute_natural_allocation() function.

Handling Events and Driving Keyboard Focus
Passing events to the area is as simple as handling events on any normal widget and then passing them to the the gtk:cell-area-event function API as they come in. Usually the gtk:cell-area object is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the "focus-changed" signal to fire. As well as the "add-editable" signal in the case that an editable cell was clicked and needs to start editing. You can call the gtk:cell-area-stop-editing function at any time to cancel any cell editing that is currently in progress.

The gtk:cell-area object drives keyboard focus from cell to cell in a way similar to gtk:widget object. For layouting widgets that support giving focus to cells it is important to remember to pass the GTK_CELL_RENDERER_FOCUSED value to the area functions for the row that has focus and to tell the area to paint the focus at render time.

Layouting widgets that accept focus on cells should implement the focus() virtual method. The layouting widget is always responsible for knowing where gtk:tree-model rows are rendered inside the widget, so at focus() time the layouting widget should use the gtk:cell-area methods to navigate focus inside the area and then observe the gtk:direction-type value to pass the focus to adjacent rows and areas.

A basic example of how the focus() virtual method should be implemented:

Example: Implementing keyboard focus navigation
static gboolean
foo_focus (GtkWidget       *widget,
           GtkDirectionType direction)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;
  gint        focus_row;
  gboolean    have_focus = FALSE;

focus_row = priv->focus_row;

if (!gtk_widget_has_focus (widget)) gtk_widget_grab_focus (widget);

valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row); while (valid) { gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE);

if (gtk_cell_area_focus (priv->area, direction)) { priv->focus_row = focus_row; have_focus = TRUE; break; } else { if (direction == GTK_DIR_RIGHT || direction == GTK_DIR_LEFT) break; else if (direction == GTK_DIR_UP || direction == GTK_DIR_TAB_BACKWARD) { if (focus_row == 0) break; else { focus_row--; valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row); } } else { if (focus_row == last_row) break; else { focus_row++; valid = gtk_tree_model_iter_next (priv->model, &iter); } } } } return have_focus; }
Note that the layouting widget is responsible for matching the gtk:direction-type values to the way it lays out its cells.

Cell Properties
The gtk:cell-area class introduces cell properties for gtk:cell-renderer objects. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a gtk:cell-area-box object a cell might "expand" and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to "align" with adjacent rows which were requested and rendered with the same gtk:cell-area-context object.

Use the gtk_cell_area_class_install_cell_property() function to install cell properties for a cell area class and the gtk:cell-area-class-find-cell-property or gtk:cell-area-class-list-cell-properties functions to get information about existing cell properties.

To set or get the value of a cell property, use the gtk:cell-area-cell-property, gtk:cell-area-cell-get, and gtk:cell-area-cell-set functions.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
Signal Details:
The "add-editable" signal
lambda (area renderer editable cell-area path)    :run-first      
area
The gtk:cell-area object where editing started.
renderer
The gtk:cell-renderer object that started the edited.
editable
The gtk:cell-editable widget to add.
cell-area
The gtk:widget object relative gdk:rectangle coordinates where editable should be added.
path
The gtk:tree-path string this edit was initiated for.
Indicates that editing has started on renderer and that editable should be added to the owning cell-layouting widget at cell-area.
The "apply-attributes" signal
lambda (area model iter is-expander is-expanded)    :run-first      
area
The gtk:cell-area object to apply the attributes to.
model
The gtk:tree-model object to apply the attributes from.
iter
The gtk:tree-iter instance indicating which row to apply the attributes of.
is-expander
Whether the view shows children for this row.
is-expanded
Whether the view is currently showing the children of this row.
The signal is emitted whenever applying attributes to the cell area from the model.
The "focus-changed" signal
lambda (area renderer path)    :run-first      
area
The gtk:cell-area object where focus changed.
renderer
The gtk:cell-renderer object that has focus.
path
The current gtk:tree-path string set for area.
Indicates that focus changed on the cell area. The signal is emitted either as a result of focus handling or event handling. It is possible that the signal is emitted even if the currently focused renderer did not change, this is because focus may change to the same renderer in the same cell area for a different row of data.
The "remove-editable" signal
lambda (area renderer editable)    :run-first      
area
The gtk:cell-area object where editing finished.
renderer
The gtk:cell-renderer object that finished editeding.
editable
The gtk:cell-editable widget to remove.
Indicates that editing finished on renderer and that editable should be removed from the owning cell-layouting widget.
See also:
2024-7-7
Accessor gtk:cell-area-edit-widget (object)
Syntax:
(gtk:cell-area-edit-widget object) => widget
Arguments:
object -- a gtk:cell-area object
widget -- a gtk:cell-editable widget
Details:
Accessor of the edit-widget slot of the gtk:cell-area class. The gtk:cell-area-edit-widget function gets the widget currently used to edit the currently edited cell.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Accessor gtk:cell-area-edited-cell (object)
Syntax:
(gtk:cell-area-edited-cell object) => renderer
Arguments:
object -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object
Details:
Accessor of the edited-cell slot of the gtk:cell-area class. The gtk:cell-area-edited-cell function gets the gtk:cell-renderer object in the area that is currently being edited.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Accessor gtk:cell-area-focus-cell (object)
Syntax:
(gtk:cell-area-edited-cell object) => renderer
(setf (gtk:cell-area-edited-cell object) renderer
Arguments:
object -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to give focus to
Details:
Accessor of the focus-cell slot of the gtk:cell-area class. The gtk:cell-area-focus-cell function retrieves the currently focused cell for the area. The (setf gtk:cell-area-focus-cell) function explicitly sets the currently focused cell to renderer.

This is generally called by implementations of the GtkCellAreaClass.focus() or GtkCellAreaClass.event() functions, however it can also be used to implement functions such as the gtk:tree-view-set-cursor-on-cell function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-add (area renderer)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to add to area
Details:
Adds a cell renderer to the cell area with the default child cell properties.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-remove (area renderer)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to remove from area
Details:
Removes a cell renderer from the cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-has-renderer (area renderer)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to check
Returns:
True if renderer is in the area.
Details:
Checks if the cell area contains renderer.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Callback gtk:cell-callback
Syntax:
lambda (renderer) => result
Arguments:
renderer -- a gtk:cell-renderer object to operate on
result -- true to stop iterating over cells
Details:
The type of the callback function used for iterating over the cell renderers of a gtk:cell-area object, see the gtk:cell-area-foreach function.
See also:
2024-7-7
Function gtk:cell-area-foreach (area func)
Arguments:
area -- a gtk:cell-area object
func -- a gtk:cell-callback callback function to call
Details:
Calls a callback function for every cell renderer in the cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Callback gtk:cell-alloc-callback
Syntax:
lambda (renderer cell background) => result
Arguments:
renderer -- a gtk:cell-renderer object to operate on
cell -- a gdk:rectangle area allocated to renderer inside the rectangle provided to the gtk:cell-area-foreach-alloc function
background -- a gdk:rectangle background area for renderer inside the background area provided to the gtk:cell-area-foreach-alloc function
result -- true to stop iterating over cells
Details:
The type of the callback function used for iterating over the cell renderers of a gtk:cell-area object, see the gtk:cell-area-foreach-alloc function.
See also:
2024-7-7
Function gtk:cell-area-foreach-alloc (area context widget cell background func)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object
widget -- a gtk:widget object that area is rendering to
cell -- a gdk:rectangle instance with the relative coordinates and size of widget for rendering area
background -- a gdk:rectangle instance with the relative coordinates of the background for rendering area
func -- a gtk:cell-alloc-callback callback function
Details:
Calls the callback function for every gtk:cell-renderer object in the cell area with the allocated rectangle inside cell.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-event (area context widget event cell flags)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object for this row of data
widget -- a gtk:widget object that area is rendering to
event -- a gdk:event instance to handle
cell -- a gdk:rectangle instance with the widget relative coordinates for area
flags -- a gtk:cell-renderer-state value for area in this row
Returns:
True if the event was handled by the cell area.
Details:
Delegates event handling to a cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-26
Function gtk:cell-area-snapshot (area context widget snapshot background cell flags paint-focus)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object for this row of data
widget -- a gtk:widget object that area is rendering to
snapshot -- a gtk:snapshot object to draw to
cell -- a gdk:rectangle instance with the widget relative coordinates for area
flags -- a gtk:cell-renderer-state value for area in this row
paint-focus -- a gtk:cell-renderer-state value for area in this row
Details:
Snapshots area's cells according to area's layout onto at the given coordinates.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-cell-allocation (area context widget renderer cell)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object used to hold sizes for area
widget -- a gtk:widget object that area is rendering on
renderer -- a gtk:cell-renderer object to get the allocation for
cell -- a gdk:rectangle instance with the whole allocated area for area in widget for this row
Returns:
The gdk:rectangle instance with the allocation for renderer.
Details:
Derives the allocation of the cell renderer inside the cell area if cell were to be renderered in area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-cell-at-position (area context widget cell x y)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object used to hold sizes for area
widget -- a gtk:widget object that area is rendering on
cell -- a gdk:rectangle instance with the whole allocated area for area in widget for this row
x -- an integer with the x position
y -- an integer with the y position
Returns:
The gtk:cell-renderer object at x and y for the first value and the gdk:rectangle allocation for the inner allocated area of the returned cell renderer.
Details:
Gets the gtk:cell-renderer object at x and y coordinates inside area and the full cell allocation for it inside cell.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-create-context (area)
Arguments:
area -- a gtk:cell-area object
Returns:
The newly created gtk:cell-area-context object which can be used with area.
Details:
Creates a cell area context to be used with area for all purposes. The gtk:cell-area-context object stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times, that is, one should render and handle events with the same gtk:cell-area-context object which was used to request the size of those rows of data.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-10-9
Function gtk:cell-area-copy-context (area context)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object to copy
Returns:
The newly created gtk:cell-area-context object copy of context.
Details:
This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation.

For instance, the gtk:icon-view widget creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. The gtk:icon-view widget uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-request-mode (area)
Arguments:
area -- a gtk:cell-area object
Returns:
The gtk:size-request-mode value preferred by area.
Details:
Gets whether the area prefers a height-for-width layout or a width-for-height layout.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-preferred-width (area context widget)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object to perform this request with
widget -- a gtk:widget object where area will be rendering
Returns:
minimum -- an integer with the minimum width, or nil
natural -- an integer with the natural width, or nil
Details:
Retrieves an initial minimum and natural width of the cell area. The area argument will store some geometrical information in context along the way, when requesting sizes over an arbitrary number of rows, its not important to check the minimum and natural of this call but rather to consult the gtk:cell-area-context-preferred-width function after a series of requests.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-preferred-height-for-width (area context widget width)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object which has already been requested for widths
widget -- a gtk:widget object where area will be rendering
width -- an integer with the width for which to check the height of this area
Returns:
minimum -- an integer with the minimum height, or nil
natural -- an integer with the natural height, or nil
Details:
Retrieves a minimum and natural height of the cell area if it would be given the specified width. The area argument stores some geometrical information in context along the way while calling the gtk:cell-area-preferred-width function. It is important to perform a series of gtk:cell-area-preferred-width requests with context first and then call the gtk:cell-area-preferred-height-for-width function on each cell area individually to get the height for width of each fully requested row.

If at some point, the width of a single row changes, it should be requested with the gtk:cell-area-preferred-width function again and then the full width of the requested rows checked again with the gtk:cell-area-context-preferred-width function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-preferred-height (area context widget)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object to perform this request with
widget -- a gtk:widget where area will be rendering
Returns:
minimum -- an integer with the minimum height, or nil
natural -- an integer with the natural height, or nil
Details:
Retrieves an initial minimum and natural height of the cell area. The area argument will store some geometrical information in context along the way, when requesting sizes over an arbitrary number of rows, its not important to check the minimum and natural of this call but rather to consult the gtk:cell-area-context-preferred-height function after a series of requests.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-preferred-width-for-height (area context widget height)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object which has already been requested for widths
widget -- a gtk:widget object where area will be rendering
height -- an integer with the height for which to check the width of this area
Returns:
minimum -- an integer with the minimum width, or nil
natural -- an integer with the natural width, or nil
Details:
Retrieves a minimum and natural width of the cell area if it would be given the specified height. The area argument stores some geometrical information in context along the way while calling the gtk:cell-area-preferred-height function. It is important to perform a series of the gtk:cell-area-preferred-height function requests with context first and then call the gtk:cell-area-preferred-width-for-height function on each cell area individually to get the height for width of each fully requested row.

If at some point, the height of a single row changes, it should be requested with the gtk:cell-area-preferred-height function again and then the full height of the requested rows checked again with the gtk:cell-area-context-preferred-height function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-current-path-string (area)
Arguments:
area -- a gtk:cell-area object
Returns:
The current gtk:tree-path string for the current attributes applied to area.
Details:
Gets the current gtk:tree-path string for the currently applied gtk:tree-iter iterator. This is implicitly updated when the gtk:cell-area-apply-attributes function is called and can be used to interact with renderers from gtk:cell-area subclasses.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-apply-attributes (area model iter is-expander is-expanded)
Arguments:
area -- a gtk:cell-area object
model -- a gtk:tree-model object to pull values from
iter -- a gtk:tree-iter iterator in model to apply values for
is-expander -- a boolean whether iter has children
is-expanded -- a boolean whether iter is expanded in the view and children are visible
Details:
Applies any connected attributes to the renderers in the cell area by pulling the values from the tree model.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-attribute-connect (area renderer attribute column)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to connect an attribute for
attribute -- a string with the attribute name
column -- an integer for the gtk:tree-model object column to fetch attribute values from
Details:
Connects an attribute to apply values from column for the tree model in use.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-attribute-disconnect (area renderer attribute)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to disconnect an attribute for
attribute -- a string with the attribute name
Details:
Disconnects attribute for the renderer in the cell area so that attribute will no longer be updated with values from the model.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-attribute-column (area renderer attribute)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object
attribute -- a string with an attribute on the renderer
Returns:
The integer with the model column, or -1.
Details:
Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-class-find-cell-property (gtype property)
Arguments:
gtype -- a g:type-t type ID
property -- a string with the name of the cell property to find
Returns:
The g:param-spec instance of the cell property or a cffi:null-pointer if the gtype type has no child property with that name.
Details:
Finds a cell property of a cell area type by name.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-12-29
Function gtk:cell-area-class-list-cell-properties (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
The list of g:param-spec instances.
Details:
Returns the cell properties of a cell area class.
Notes:
In the Lisp binding we pass the type of a cell area class and not a pointer to the cell area class as argument to the function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-add-with-properties (area renderer &rest args)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to be placed inside area
args -- property names and values
Details:
Adds renderer to area, setting cell properties at the same time. See the gtk:cell-area-add and gtk:cell-area-cell-set functions for more details.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-cell-set (area renderer &rest args)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object which is cell inside area
args -- cell property names and values
Details:
Sets one or more cell properties for the cell in the cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-cell-get (area renderer &rest args)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object which is inside area
args -- strings with the cell property names to get the values for
Returns:
The list with the values of the cell properties.
Details:
Gets the values of one or more cell properties for the cell renderer in the cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-cell-property (area renderer property)
Syntax:
(gtk:cell-area-property area renderer property) => value
(setf (gtk:cell-area-property area renderer property) value)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object which is inside area
property -- a string with the name of the cell property
value -- a value for the property
Details:
Gets or sets the value of a cell property for the cell renderer inside the cell area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-7-7
Function gtk:cell-area-is-activatable (area)
Arguments:
area -- a gtk:cell-area object
Returns:
The boolean whether area can do anything when activated.
Details:
Returns whether the cell area can do anything when activated, after applying new attributes to area.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-activate (area context widget cell flags edit-only)
Arguments:
area -- a gtk:cell-area object
context -- a gtk:cell-area-context object in context with the current row data
widget -- a gtk:widget object that area is rendering on
cell -- a gdk:rectangle instance with the size and location of area relative to allocation of the widget
flags -- a gtk:cell-renderer-state value for area for this row of data
edit-only -- if true then only cell renderers that are :editable will be activated
Returns:
The boolean whether area was successfully activated.
Details:
Activates area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-focus (area direction)
Arguments:
area -- a gtk:cell-area object
direction -- a value of the gtk:direction-type enumeration
Returns:
True if focus remains inside area as a result of this call.
Details:
This should be called by the owning layout widget of the cell area when focus is to be passed to area, or moved within area for a given direction and row data.

Implementing gtk:cell-area classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-add-focus-sibling (area renderer sibling)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object expected to have focus
sibling -- a gtk:cell-renderer object to add to the focus area of the cell renderer
Details:
Adds sibling to focusable area of the cell renderer, focus will be drawn around renderer and all of its siblings if renderer can focus for a given row.

Events handled by focus siblings can also activate the given focusable renderer.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-remove-focus-sibling (area renderer sibling)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object expected to have focus
sibling -- a gtk:cell-renderer object to remove from the focus area of the cell renderer
Details:
Removes sibling from the focus sibling list of the cell renderer. See the gtk:cell-area-add-focus-sibling function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-is-focus-sibling (area renderer sibling)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object expected to have focus
sibling -- a gtk:cell-renderer object to check against the sibling list of the cell renderer
Returns:
True if sibling is a focus sibling of renderer.
Details:
Returns whether sibling is one of the focus siblings of the cell renderer. See the gtk:cell-area-add-focus-sibling function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-focus-siblings (area renderer)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object expected to have focus
Returns:
The list of gtk:cell-renderer objects.
Details:
Gets the focus sibling cell renderers for renderer.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-focus-from-sibling (area renderer)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object
Returns:
The gtk:cell-renderer object for which renderer is a sibling, or nil.
Details:
Gets the cell renderer which is expected to be focusable for which renderer is, or may be a sibling.

This is handy for gtk:cell-area subclasses when handling events, after determining the cell renderer at the event location it can then chose to activate the focus cell for which the event cell may have been a sibling.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-activate-cell (area widget renderer event cell flags)
Arguments:
area -- a gtk:cell-area object
widget -- a gtk:widget object that area is rendering onto
renderer -- a gtk:cell-renderer object in area to activate
event -- a gdk:event instance for which cell activation should occur
cell -- a gdk:rectangle instance in widget relative coordinates of renderer for the current row
flags -- a value of the gtk:cell-renderer-state flags for renderer
Returns:
The boolean whether cell activation was successful.
Details:
This is used by gtk:cell-area subclasses when handling events to activate cells, the base gtk:cell-area class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-26
Function gtk:cell-area-stop-editing (area canceled)
Arguments:
area -- a gtk:cell-area object
canceled -- a boolean whether editing was canceled
Details:
Explicitly stops the editing of the currently edited cell. If the canceled argument is true, the currently edited cell renderer will emit the "editing-canceled" signal, otherwise the "editing-done" signal will be emitted on the current edit widget.

See the gtk:cell-area-edited-cell and gtk:cell-area-edit-widget functions.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-inner-cell-area (area widget cell)
Arguments:
area -- a gtk:cell-area object
widget -- a gtk:widget object that area is rendering onto
cell -- a gdk:rectangle instance with the widget relative coordinates where one of the cells of the cell area is to be placed
Returns:
The gdk:rectangle instance with the inner cell area.
Details:
This is a convenience function for gtk:cell-area implementations to get the inner area where a given gtk:cell-renderer object will be rendered. It removes any padding previously added by the gtk:cell-area-request-renderer function.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7
Function gtk:cell-area-request-renderer (area renderer orientation widget for-size)
Arguments:
area -- a gtk:cell-area object
renderer -- a gtk:cell-renderer object to request size for
orientation -- a value of the gtk:orientation enumeration in which to request size
widget -- a gtk:widget object that area is rendering onto
for-size -- an integer with the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned
Returns:
minimum -- an integer with the minimum size, or nil
natural -- an integer with the natural size, or nil
Details:
This is a convenience function for gtk:cell-area implementations to request size for cell renderers. It is important to use this function to request size and then use the gtk:cell-area-inner-cell-area function at render and event time since this function will add padding around the cell for focus painting.
Warning:
The gtk:cell-area implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-7-7

GtkCellAreaBox

Class gtk:cell-area-box
Superclasses:
Documented Subclasses:
None
Direct Slots:
spacing
The spacing property of type :int (Read / Write)
The amount of space to reserve between cells.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:cell-area-box object renders cell renderers into a row or a column depending on its orientation. The gtk:cell-area-box implementation uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a gtk:cell-area-box object. There are two reference positions: the start and the end of the box. When the gtk:cell-area-box object is oriented in the :vertical orientation, the start is defined as the top of the box and the end is defined as the bottom. In the :horizontal orientation start is defined as the left side and the end is defined as the right side.

Alignments of gtk:cell-renderer objects rendered in adjacent rows can be configured by configuring the align child cell property with the gtk:cell-area-cell-property function or by specifying the align argument to the gtk:cell-area-box-pack-start and gtk:cell-area-box-pack-end functions.
Warning:
The gtk:cell-area-box implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-2-21
Accessor gtk:cell-area-box-spacing (object)
Syntax:
(gtk:cell-area-box-spacing object) => spacing
(setf (gtk:cell-area-box-spacing object) spacing)
Arguments:
object -- a gtk:cell-area-box object
spacing -- an integer with the space to add between gtk:cell-renderer objects
Details:
Accessor of the spacing slot of the gtk:cell-area-box class. The gtk:cell-area-box-spacing function gets the spacing added between cell renderers. The (setf gtk:cell-area-box-spacing) function sets the spacing to add between cell renderers.
Warning:
The gtk:cell-area-box implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-2-21
Function gtk:cell-area-box-new ()
Returns:
The newly created gtk:cell-area-box object.
Details:
Creates a new cell area box.
Warning:
The gtk:cell-area-box implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-2-21
Function gtk:cell-area-box-pack-start (box renderer &key expand align fixed)
Arguments:
box -- a gtk:cell-area-box widget
renderer -- a gtk:cell-renderer object to add
expand -- a boolean whether renderer should receive extra space when the area receives more than its natural size
align -- a boolean whether renderer should be aligned in adjacent rows
fixed -- a boolean whether renderer should have the same size in all rows
Details:
Adds a renderer to the cell area box, packed with reference to the start of the box. The renderer is packed after any other gtk:cell-renderer object packed with reference to the start of the box.
Warning:
The gtk:cell-area-box implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-2-21
Function gtk:cell-area-box-pack-end (box child &key expand align fixed)
Arguments:
box -- a gtk:cell-area-box widget
renderer -- a gtk:cell-renderer object to add
expand -- a boolean whether renderer should receive extra space when the area receives more than its natural size
align -- a boolean whether renderer should be aligned in adjacent rows
fixed -- a boolean whether renderer should have the same size in all rows
Details:
Adds a renderer to cell area box, packed with reference to the end of the box. The renderer is packed after, away from end of, any other gtk:cell-renderer object packed with reference to the end of the box.
Warning:
The gtk:cell-area-box implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-2-21

GtkCellAreaContext

Class gtk:cell-area-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
area
The area property of type gtk:cell-area (Read / Write / Construct)
The cell area this context was created by.
minimum-height
The minimum-height property of type :int (Read)
The minimum height for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-height function.
Allowed values: >= -1
Default value: -1
minimum-width
The minimum-width property of type :int (Read)
The minimum width for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-width function.
Allowed values: >= -1
Default value: -1
natural-height
The natural-height property of type :int (Read)
The natural height for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-height function.
Allowed values: >= -1
Default value: -1
natural-width
The natural-width property of type :int (Read)
The natural width for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-width function.
Allowed values: >= -1
Default value: -1
Slot Access Functions:
Details:
The gtk:cell-area-context object is created by a given gtk:cell-area implementation via its create_context() virtual method and is used to store cell sizes and alignments for a series of gtk:tree-model rows that are requested and rendered in the same context.

The gtk:cell-layout widget can create any number of contexts in which to request and render groups of data rows. However its important that the same context which was used to request sizes for a given gtk:tree-model row also be used for the same row when calling other gtk:cell-area APIs such as the gtk:cell-renderer-* and gtk:cell-area-event functions.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Accessor gtk:cell-area-context-area (object)
Syntax:
(gtk:cell-area-context-area object) => area
Arguments:
context -- a gtk:cell-area-context object
area -- a gtk:cell-area object
Details:
Accessor of the area slot of the gtk:cell-area-context class. The gtk:cell-area-context-area function fetches the cell area the context was created by.

This is generally unneeded by layouting widgets. However it is important for the context implementation itself to fetch information about the area it is being used for. For instance at GtkCellAreaContextClass.allocate() time its important to know details about any cell spacing that the cell area is configured with in order to compute a proper allocation.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Accessor gtk:cell-area-context-minimum-height (object)
Syntax:
(gtk:cell-area-context-minimum-height object) => height
(setf (gtk:cell-area-context-minimum-height object) height
Arguments:
context -- a gtk:cell-area-context object
height -- an integer with the minimum height
Details:
Accessor of the minimum-height slot of the gtk:cell-area-context class. The minimum height for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-height function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Accessor gtk:cell-area-context-minimum-width (object)
Syntax:
(gtk:cell-area-context-minimum-width object) => width
(setf (gtk:cell-area-context-minimum-width object) width
Arguments:
context -- a gtk:cell-area-context object
width -- an integer with the minimum width
Details:
Accessor of the minimum-width slot of the gtk:cell-area-context class. The minimum width for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-width function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Accessor gtk:cell-area-context-natural-height (object)
Syntax:
(gtk:cell-area-context-natural-height object) => height
(setf (gtk:cell-area-context-natural-height object) height
Arguments:
context -- a gtk:cell-area-context object
height -- an integer with the natural height
Details:
Accessor of the natural-height slot of the gtk:cell-area-context class. The natural height for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-height function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Accessor gtk:cell-area-context-natural-width (object)
Syntax:
(gtk:cell-area-context-natural-width object) => width
(setf (gtk:cell-area-context-natural-width object) width
Arguments:
context -- a gtk:cell-area-context object
width -- an integer with the natural width
Details:
Accessor of the natural-width slot of the gtk:cell-area-context class. The natural width for the cell area in this context for all gtk:tree-model rows that this context was requested for using the gtk:cell-area-preferred-width function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
2024-2-21
Function gtk:cell-area-context-allocate (context width height)
Arguments:
context -- a gtk:cell-area-context object
width -- an integer with the allocated width for all gtk:tree-model rows rendered with context, or -1
height -- an integer with the allocated height for all gtk:tree-model rows rendered with context, or -1
Details:
Allocates a width and/or a height for all rows which are to be rendered with context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for gtk:tree-view when the fixed-height-mode property is enabled.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-reset (context)
Arguments:
context -- a gtk:cell-area-context object
Details:
Resets any previously cached request and allocation data. When underlying gtk:tree-model data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow, this is usually an option for views rendering large data stores as a measure of optimization, then only the row that changed or was inserted needs to be (re)requested with the gtk:cell-area-preferred-width function.

When the new overall size of the context requires that the allocated size changes, or whenever this allocation changes at all, the variable row sizes need to be re-requested for every row.

For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using the gtk:cell-area-preferred-height-for-width function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-preferred-width (context)
Arguments:
context -- a gtk:cell-area-context object
Returns:
minimum -- an integer with the minimum width, or nil
natural -- an integer with the natural width, or nil
Details:
Gets the accumulative preferred width for all rows which have been requested with this context. After the gtk:cell-area-context-reset function is called and/or before ever requesting the size of a cell area, the returned values are 0.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-preferred-height (context)
Arguments:
context -- a gtk:cell-area-context object
Returns:
minimum -- an integer with the minimum height, or nil
natural -- an integer with the natural height, or nil
Details:
Gets the accumulative preferred height for all rows which have been requested with this context. After the gtk:cell-area-context-reset function is called and/or before ever requesting the size of a cell area, the returned values are 0.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-preferred-height-for-width (context width)
Arguments:
context -- a gtk:cell-area-context object
width -- an integer with a proposed width for allocation
Returns:
minimum -- an integer with the minimum height, or nil
natural -- an integer with the natural height, or nil
Details:
Gets the accumulative preferred height for width for all rows which have been requested for the same said width with this context. After the gtk:cell-area-context-reset function is called and/or before ever requesting the size of a cell area, the returned values are -1.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-preferred-width-for-height (context height)
Arguments:
context -- a gtk:cell-area-context object
height -- an integer with a proposed height for allocation
Returns:
minimum -- an integer with the minimum width, or nil
natural -- an integer with the natural width, or nil
Details:
Gets the accumulative preferred width for height for all rows which have been requested for the same said height with this context. After the gtk:cell-area-context-reset function is called and/or before ever requesting the size of a cell area, the returned values are -1.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-allocation (context)
Arguments:
context -- a gtk:cell-area-context object
Returns:
width -- an integer with the allocated width, or nil
height -- an integer with the allocated height, or nil
Details:
Fetches the current allocation size for context. If the context was not allocated in width or height, or if the context was recently reset with the gtk:cell-area-context-reset function, the returned value will be -1.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-push-preferred-width (context minimum natural)
Arguments:
context -- a gtk:cell-area-context object
minimum -- an integer with the proposed new minimum width for context
natural -- an integer with the proposed new natural width for context
Details:
Causes the minimum and/or natural width to grow if the new proposed sizes exceed the current minimum and natural width. This is used by gtk:cell-area-context implementations during the request process over a series of gtk:tree-model rows to progressively push the requested width over a series of the gtk:cell-area-preferred-width requests function.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21
Function gtk:cell-area-context-push-preferred-height (context minimum natural)
Arguments:
context -- a gtk:cell-area-context object
minimum -- an integer with the proposed new minimum height for context
natural -- an integer with the proposed new natural height for context
Details:
Causes the minimum and/or natural height to grow if the new proposed sizes exceed the current minimum and natural height. This is used by gtk:cell-area-context implementations during the request process over a series of gtk:tree-model rows to progressively push the requested height over a series of the gtk:cell-area-preferred-height function requests.
Warning:
The gtk:cell-area-context implementation is deprecated since 4.10. This object will be removed in GTK 5.
See also:
#2024-2-21

GtkCellEditable

Interface gtk:cell-editable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
editing-canceled
The editing-canceled property of type :boolean (Read / Write)
Indicates whether editing on the cell has been canceled.
Default value: false
Slot Access Functions:
Details:
The gtk:cell-editable interface must be implemented for widgets to be usable when editing the contents of a gtk:tree-view cell widget. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc.
Warning:
The gtk:cell-editable implementation is deprecated since 4.10, List views use widgets for displaying their contents. See the gtk:editable interface for editable text widgets.
Signal Details:
The "editing-done" signal
lambda (editable)    :run-last      
editable
The gtk:cell-editable object on which the signal was emitted.
The signal is a sign for the cell renderer to update its value from the editable argument. Implementations of the gtk:cell-editable class are responsible for emitting the signal when they are done editing, for example, the gtk:entry widget is emitting it when the user presses the Enter key. The gtk:cell-editable-editing-done function is a convenience method for emitting the "editing-done" signal.
The "remove-widget" signal
lambda (editable)    :run-last      
editable
The gtk:cell-editable object on which the signal was emitted.
The signal is meant to indicate that the cell is finished editing, and the widget may now be destroyed. Implementations of the gtk:cell-editable class are responsible for emitting the signal when they are done editing. It must be emitted after the "editing-done" signal, to give the cell renderer a chance to update the value of the cell before the widget is removed. The gtk:cell-editable-remove-widget function is a convenience method for emitting the "remove-widget" signal.
See also:
2024-11-5
Accessor gtk:cell-editable-editing-canceled (object)
Syntax:
(gtk:cell-editable-editing-canceled object) => canceled
(setf (gtk:cell-editable-editing-canceled object) canceled)
Arguments:
object -- a gtk:cell-editable object
canceled -- a boolean whether editing on the cell has been canceled
Details:
Accessor of the editing-canceled slot of the gtk:cell-editable class. Indicates whether editing on the cell has been canceled.
Warning:
The gtk:cell-editable implementation is deprecated since 4.10, Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:cell-editable-start-editing (editable event)
Arguments:
editable -- a gtk:cell-editable object
event -- a gdk:event instance that began the editing process, or nil if editing was initiated programmatically
Details:
Begins editing on a cell editable. The gtk:cell-renderer object for the cell creates and returns a gtk:cell-editable object from the gtk:cell-renderer-start-editing function, configured for the gtk:cell-renderer type.

The gtk:cell-editable-start-editing function can then set up the editable argument suitably for editing a cell, for example, making the Esc key emit the "editing-done" signal.

Note that the editable argument is created on-demand for the current edit. Its lifetime is temporary and does not persist across other edits and/or cells.
Warning:
The gtk:cell-editable implementation is deprecated since 4.10, Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:cell-editable-editing-done (editable)
Arguments:
editable -- a gtk:cell-editable object
Details:
Emits the "editing-done" signal.
Warning:
The gtk:cell-editable implementation is deprecated since 4.10, Please do not use it in newly written code.
See also:
#2024-11-5
Function gtk:cell-editable-remove-widget (editable)
Arguments:
editable -- a gtk:cell-editable object
Details:
Emits the "remove-widget" signal.
Warning:
The gtk:cell-editable implementation is deprecated since 4.10, Please do not use it in newly written code.
See also:
#2024-11-5

GtkCellRenderer

GFlags gtk:cell-renderer-state
Declaration:
(gobject:define-gflags "GtkCellRendererState" cell-renderer-state
  (:export t
   :type-initializer "gtk_cell_renderer_state_get_type")
  (:selected    #.(ash 1 0))
  (:prelit      #.(ash 1 1))
  (:insensitive #.(ash 1 2))
  (:sorted      #.(ash 1 3))
  (:focused     #.(ash 1 4))
  (:expandable  #.(ash 1 5))
  (:expanded    #.(ash 1 6)))  
Values:
:selected
The cell is currently selected, and probably has a selection colored background to render to.
:prelit
The mouse is hovering over the cell.
:insensitive
The cell is drawn in an insensitive manner.
:sorted
The cell is in a sorted row.
:focused
The cell is in the focus row.
:expandable
The cell is in a row that can be expanded.
:expanded
The cell is in a row that is expanded.
Details:
Tells how a cell is to be rendererd.
See also:
2024-5-15
GEnum gtk:cell-renderer-mode
Declaration:
(gobject:define-genum "GtkCellRendererMode" cell-renderer-mode
  (:export t
   :type-initializer "gtk_cell_renderer_mode_get_type")
  (:inert 0)
  (:activatable 1)
  (:editable 2))  
Values:
:inert
The cell is just for display and cannot be interacted with. Note that this does not mean that the row being drawn cannot be selected - just that a particular element of it cannot be individually modified.
:activatable
The cell can be clicked.
:editable
The cell can be edited or otherwise modified.
Details:
Identifies how the user can interact with a particular cell.
See also:
2024-5-15
Class gtk:cell-renderer
Superclasses:
gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
cell-background
The cell-background property of type :string (Write)
The cell background color as a string.
Default value: nil
cell-background-rgba
The cell-background-rgba property of type gdk:rgba (Read / Write)
The cell background RGBA color.
cell-background-set
The cell-background-set property of type :boolean (Read / Write)
Whether this tag affects the cell background color.
Default value: false
editing
The editing property of type :boolean (Read)
Whether the cell renderer is currently in editing mode.
Default value: false
height
The height property of type :int (Read / Write)
The fixed height.
Allowed values: >= -1
Default value: -1
is-expanded
The is-expanded property of type :boolean (Read / Write)
Whether the row is an expander row, and is expanded.
Default value: false
is-expander
The is-expander property of type :boolean (Read / Write)
Whether the row has children.
Default value: false
mode
The mode property of type gtk:cell-renderer-mode (Read / Write)
The editable mode of the cell renderer.
Default value: :inert
sensitive
The sensitive property of type :boolean (Read / Write)
Whether to display the cell sensitive.
Default value: true
visible
The visible property of type :boolean (Read / Write)
Whether to display the cell.
Default value: true
width
The width property of type :int (Read / Write)
The fixed width.
Allowed values: >= -1
Default value: -1
xalign
The xalign property of type :float (Read / Write)
The horizontal alignment, from 0.0 (left) to 1.0 (right). Reversed for RTL layouts.
Allowed values: [0.0,1.0]
Default value: 0.5
xpad
The xpad property of type :uint (Read / Write)
The amount of space to add on the left and right, in pixels.
Default value: 0
yalign
The yalign property of type :float (Read / Write)
The vertical alignment, from 0.0 (top) to 1.0 (bottom).
Allowed values: [0.0,1.0]
Default value: 0.5
ypad
The ypad property of tpye :uint (Read / Write)
The amount of space to add on the top and bottom, in pixels.
Default value: 0
Slot Access Functions:
Details:
The gtk:cell-renderer class is a base class of a set of objects used for rendering a cell to a cairo:context-t context. These objects are used primarily by the gtk:tree-view widget, though they are not tied to them in any specific way. It is worth noting that the gtk:cell-renderer object is not a gtk:widget object and cannot be treated as such.

The primary use of a gtk:cell-renderer object is for drawing a certain graphical elements on a Cairo context. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it is not expected that a gtk:cell-renderer object keep any permanent state around. Instead, any state is set just prior to use using GObjects property system. Then, the cell is measured using the gtk:cell-renderer-preferred-size function. Finally, the cell is rendered in the correct location using the gtk:cell-renderer-snapshot function.

There are a number of rules that must be followed when writing a new gtk:cell-renderer class. First and formost, its important that a certain set of properties will always yield a cell renderer of the same size, barring a style change. The gtk:cell-renderer also has a number of generic properties that are expected to be honored by all children.

Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be "activatable" like the gtk:cell-renderer-toggle object, which toggles when it gets activated by a mouse click, or it can be "editable" like the gtk:cell-renderer-text object, which allows the user to edit the text using a widget implementing the gtk:cell-editable interface, for example the gtk:entry widget. To make a cell renderer activatable or editable, you have to implement the GtkCellRendererClass.activate or GtkCellRendererClass.start_editing virtual functions, respectively.

Many properties of the gtk:cell-renderer class and its subclasses have a corresponding set property, for example, cell-background-set corresponds to cell-background. These set properties reflect whether a property has been set or not. You should not set them independently.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
Signal Details:
The "editing-canceled" signal
lambda (renderer)    :run-first      
renderer
The gtk:cell-renderer object which received the signal.
The signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses the Escape key. See also the gtk:cell-renderer-stop-editing function.
The "editing-started" signal
lambda (renderer editable path)    :run-first      
renderer
The gtk:cell-renderer object which received the signal.
editable
The gtk:cell-editable widget.
path
The string with the path identifying the edited cell.
The signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on editable, for example, adding a gtk:entry-completion object or setting up additional columns in a gtk:combo-box widget. Note that GTK does not guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of the editable argument before doing any specific setup.
See also:
2024-5-15
Accessor gtk:cell-renderer-cell-background (object)
Syntax:
(setf (gtk:cell-renderer-cell-background object) background)
Arguments:
object -- a gtk:cell-renderer object
background -- a string with the cell background color
Details:
Accessor of the cell-background slot of the gtk:cell-renderer class. The cell background color as a string. This property is not readable.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-cell-background-rgba (object)
Syntax:
(gtk:cell-renderer-cell-background-rgba object) => background
(setf (gtk:cell-renderer-cell-background-rgba object) background)
Arguments:
object -- a gtk:cell-renderer object
background -- a gdk:rgba color with the cell background color
Details:
Accessor of the cell-background-rgba slot of the gtk:cell-renderer class. The cell background RGBA color.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-cell-background-set (object)
Syntax:
(gtk:cell-renderer-cell-background-set object) => setting
(setf (gtk:cell-renderer-cell-background-set object) setting)
Arguments:
object -- a gtk:cell-renderer object
setting -- a boolean whether this tag affects the cell background color
Details:
Accessor of the cell-background-set slot of the gtk:cell-renderer class. Whether this tag affects the cell background color.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-editing (object)
Syntax:
(gtk:cell-renderer-editing object) => setting
Arguments:
object -- a gtk:cell-renderer object
setting -- a boolean whether the cell renderer is in editing mode
Details:
Accessor of the editing slot of the gtk:cell-renderer class. Whether the cell renderer is currently in editing mode.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-height (object)
Syntax:
(gtk:cell-renderer-height object) => height
(setf (gtk:cell-renderer-height object) height)
Arguments:
object -- a gtk:cell-renderer object
height -- an integer with the fixed height
Details:
Accessor of the height slot of the gtk:cell-renderer class. The fixed height.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-is-expanded (object)
Syntax:
(gtk:cell-renderer-is-expanded object) => setting
(setf (gtk:cell-renderer-is-expanded object) setting)
Arguments:
object -- a gtk:cell-renderer object
setting -- a boolean whether the row is expanded
Details:
Accessor of the is-expanded slot of the gtk:cell-renderer class. Whether the row is an expander row, and is expanded.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-is-expander (object)
Syntax:
(gtk:cell-renderer-is-expander object) => setting
(setf (gtk:cell-renderer-is-expander object) setting)
Arguments:
object -- a gtk:cell-renderer object
setting -- a boolean whether the row has children
Details:
Accessor of the is-expander slot of the gtk:cell-renderer class. Whether row has children.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-mode (object)
Syntax:
(gtk:cell-renderer-mode object) => mode
(setf (gtk:cell-renderer-mode object) mode)
Arguments:
object -- a gtk:cell-renderer object
mode -- a value of the gtk:cell-renderer-mode enumeration
Details:
Accessor of the mode slot of the gtk:cell-renderer class. The editable mode of the cell renderer.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
gtk:cell-renderer-mode
See also:
2024-5-15
Accessor gtk:cell-renderer-sensitive (object)
Syntax:
(gtk:cell-renderer-sensitive object) => sensitive
(setf (gtk:cell-renderer-sensitive object) sensitive)
Arguments:
object -- a gtk:cell-renderer object
sensitive -- a boolean with the sensitivity of the cell
Details:
Accessor of the sensitive slot of the gtk:cell-renderer class. The gtk:cell-renderer-sensitive function returns the cell sensitivity of the renderer. The (setf gtk:cell-renderer-sensitive) function sets the sensitivity.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-visible (object)
Syntax:
(gtk:cell-renderer-visible object) => visible
(setf (gtk:cell-renderer-visible object) visible)
Arguments:
object -- a gtk:cell-renderer object
visible -- a boolean with the visibility of the cell
Details:
Accessor of the visible of the gtk:cell-renderer class. The gtk:cell-renderer-sensitive function returns the cell visibility of the renderer. The (setf gtk:cell-renderer-sensitive) function sets the visibility.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-width (object)
Syntax:
(gtk:cell-renderer-width object) => width
(setf (gtk:cell-renderer-width object) width)
Arguments:
object -- a gtk:cell-renderer object
width -- an integer with the fixed width
Details:
Accessor of the width slot of the gtk:cell-renderer class. The fixed width.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-xalign (object)
Syntax:
(gtk:cell-renderer-xalign object) => align
(setf (gtk:cell-renderer-xalign object) align)
Arguments:
object -- a gtk:cell-renderer object
align -- a float with the x-align
Details:
Accessor of the xalign slot of the gtk:cell-renderer class. The horizontal alignment, from 0.0 (left) to 1.0 (right). Reversed for RTL layouts.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-xpad (object)
Syntax:
(gtk:cell-renderer-xpad object) => padding
(setf (gtk:cell-renderer-xpad object) padding)
Arguments:
object -- a gtk:cell-renderer object
padding -- a unsigned integer with the padding
Details:
Accessor of the xpad slot of the gtk:cell-renderer class. The amount of space to add on the left and right, in pixels.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-yalign (object)
Syntax:
(gtk:cell-renderer-yalign object) => align
(setf (gtk:cell-renderer-yalign object) align)
Arguments:
object -- a gtk:cell-renderer object
align -- a float with the y-align
Details:
Accessor of the yalign slot of the gtk:cell-renderer class. The vertical alignment, from 0.0 (top) to 1.0 (bottom).
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Accessor gtk:cell-renderer-ypad (object)
Syntax:
(gtk:cell-renderer-ypad object) => padding
(setf (gtk:cell-renderer-ypad object) padding)
Arguments:
object -- a gtk:cell-renderer object
padding -- a unsigned integer with the padding
Details:
Accessor of the ypad slot of the gtk:cell-renderer class. The amount of space to add on the top and bottom, in pixels.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
2024-5-15
Function gtk:cell-renderer-aligned-area (cell widget flags area)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell will be rendering to
flags -- a gtk:cell-renderer-state value
area -- a gdk:rectangle instance with the cell area which would be passed to the gtk:cell-renderer-snapshot function
Returns:
The gdk:rectangle area for the space inside area that would acually be used to render.
Details:
Gets the aligned area used by cell inside area. Used for finding the appropriate edit and focus rectangle.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-snapshot (cell snapshot widget background area flags)
Arguments:
cell -- a gtk:cell-renderer object
snapshot -- a gtk:snapshot object to draw to
widget -- a gtk:widget object owning window
background -- a gdk:rectangle instance with the entire cell area, including tree expanders and maybe padding on the sides
area -- a gdk:rectangle instance with the area normally rendered by a cell renderer
flags -- a gtk:cell-renderer-state value that affect rendering
Details:
Invokes the virtual render function of the cell renderer. The three passed-in rectangles are areas in the Cairo context. Most renderers will draw within area. The xalign, yalign, xpad, and ypad properties of the gtk:cell-renderer object should be honored with respect to area. The background argument includes the blank space around the cell, and also the area containing the tree expander. So the background rectangles for all cells tile to cover the entire window.
See also:
#2024-5-15
Function gtk:cell-renderer-activate (cell event widget path background area flags)
Arguments:
cell -- a gtk:cell-renderer object
event -- a gdk:event instance
widget -- a gtk:widget object that received the event
path -- a widget-dependent string representation of the event location, for example, for a gtk:tree-view widget, a string representation of the gtk:tree-path instance
background -- a gdk:rectangle with the background area as passed to the gtk:cell-renderer-snapshot function
area -- a gdk:rectangle instance with the cell area as passed to the gtk:cell-renderer-snapshot function
flags -- a gtk:cell-renderer-state value
Returns:
True if the event was consumed/handled.
Details:
Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events. For example, the gtk:cell-renderer-toggle object toggles when it gets a mouse click.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-start-editing (cell event widget path background area flags)
Arguments:
cell -- a gtk:cell-renderer object
event -- a gdk:event instance
widget -- a gtk:widget object that received the event
path -- a widget-dependent string representation of the event location, for example, for a gtk:tree-view widget, a string representation of the gtk:tree-path instance
background -- a gdk:rectangle instance with the background area as passed to the gtk:cell-renderer-snapshot function
area -- a gdk:rectangle instance with the cell area as passed to the gtk:cell-renderer-snapshot function
flags -- a gtk:cell-renderer-state value
Returns:
The new gtk:cell-editable widget, or nil.
Details:
Passes an activate event to the cell renderer for possible processing.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-stop-editing (cell canceled)
Arguments:
cell -- a gtk:cell-renderer object
canceled -- true if the editing has been canceled
Details:
Informs the cell renderer that the editing is stopped. If canceled is true, the cell renderer will emit the "editing-canceled" signal.

This function should be called by cell renderer implementations in response to the "editing-done" signal of the gtk:cell-editable widget.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-fixed-size (cell)
Syntax:
(gtk:cell-renderer-fixed-size cell) => width, height
(setf (gtk:cell-renderer-fixe-size cell) (list width height))
Arguments:
cell -- a gtk:cell-renderer object
width -- an integer with the width of the cell renderer, or -1
height -- an integer with the height of the cell renderer, or -1
Details:
The gtk:cell-renderer-fixed-size function returns width and height with the appropriate size of cell. The (setf gtk:cell-renderer-fixed-size) function sets the renderer size to be explicit, independent of the properties set.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-alignment (cell)
Syntax:
(gtk:cell-renderer-alignment cell) => xalign, yalign
(setf (gtk:cell-renderer-alignment cell) (list xalign yalign))
Arguments:
cell -- a gtk:cell-renderer object
xalign -- a single float for the x alignment of the cell renderer
yalign -- a single float for the y alignment of the cell renderer
Details:
The gtk:cell-renderer-alignment function returns the appropriate xalign and yalign values of the cell renderer. The (setf gtk:cell-renderer-alignment) function sets the alignment of the cell renderer within its available space.The xalign and yalign values are coerced to single floats before assignment.
See also:
2023-12-3
Function gtk:cell-renderer-padding (cell)
Syntax:
(gtk:cell-renderer-padding cell) => xpad, ypad
(setf (gtk:cell-renderer-padding cell) (list xpad ypad))
Arguments:
cell -- a gtk:cell-renderer object
xpad -- an integer with the x padding of the cell renderer
ypad -- an integer with the y padding of the cell renderer
Details:
The gtk:cell-renderer-padding function returns the appropriate xpad and ypad of the cell renderer. The (setf gtk:cell-renderer-padding) function sets the padding of the cell renderer.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-state (cell widget state)
Arguments:
cell -- a gtk:cell-renderer, or nil
widget -- a gtk:widget, or nil
state -- a gtk:cell-renderer-state value with the cell renderer state
Returns:
The gtk:state-flags value applying to the cell renderer.
Details:
Translates the cell renderer state to a gtk:state-flags value, based on the cell renderer and widget sensitivity, and the given gtk:cell-renderer-state value.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-is-activatable (cell)
Arguments:
cell -- a gtk:cell-renderer object
Returns:
True if the cell renderer can do anything when activated.
Details:
Checks whether the cell renderer can do something when activated.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-preferred-height (cell widget)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell renderer will be rendering to
Returns:
minimum -- an integer with the minimum height
natural -- an integer with the natural height
Details:
Retreives the minimum and natural height of a cell renderer when rendered to widget.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-preferred-height-for-width (cell widget width)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell renderer will be rendering to
width -- an integer with the size which is available for allocation
Returns:
minimum -- an integer with the minimum height
natural -- an integer with the preferred height
Details:
Retreives the minimum and natural height of a cell renderer if it were rendered to widget with the specified width.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-preferred-size (cell widget)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell renderer will be rendering to
Returns:
minimum -- a gtk:requisition instance with the minimum size
natural -- a gtk:requisition instance with the natural size
Details:
Retrieves the minimum and natural size of a cell renderer taking into account the preference for height-for-width management of widget.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-preferred-width (cell widget)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell renderer will be rendering to
Returns:
minimum -- an integer with the minimum size
natural -- an integer the natural size
Details:
Retreives the minimum and natural width of a cell renderer when rendered to the widget.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-preferred-width-for-height (cell widget height)
Arguments:
cell -- a gtk:cell-renderer object
widget -- a gtk:widget object this cell renderer will be rendering to
height -- an integer with the size which is available for allocation
Returns:
minimum -- an integer with the minimum width
natural -- an integer with the preferred width
Details:
Retreives the minimum and natural width of a cell renderer if it were rendered to widget with the specified height.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15
Function gtk:cell-renderer-request-mode (cell)
Arguments:
cell -- a gtk:cell-renderer object
Returns:
The gtk:size-request-mode mode preferred by this cell renderer.
Details:
Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.
Warning:
The gtk:cell-renderer implementation is deprecated since 4.10. List views use widgets for displaying their contents.
See also:
#2024-5-15

GtkCellRendererText

Class gtk:cell-renderer-text
Superclasses:
gtk:cell-renderer, gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
align-set
The align-set property of type :boolean (Read / Write)
Whether this tag affects the alignment mode.
Default value: false
alignment
The alignment property of type pango:alignment (Read / Write)
Specifies how to align the lines of text with respect to each other. Note that this property describes how to align the lines of text in case there are several of them. The xalign property, on the other hand, sets the horizontal alignment of the whole text.
Default value: :left
attributes
The attributes property of type pango:attr-list (Read / Write)
The list of style attributes to apply to the text of the renderer.
background
The background property of type :string (Write)
The background color as a string.
Default value: nil
background-rgba
The background-rgba property of type gdk:rgba (Read / Write)
The background color.
background-set
The background-set property of type :boolean (Read / Write)
Whether this tag affects the background color.
Default value: false
editable
The editable property of type :boolean (Read / Write)
Whether the text can be modified by the user.
Default value: false
editable-set
The editable-set property of type :boolean (Read / Write)
Whether this tag affects text editability.
Default value: false
ellipsize
The ellipsize property of type pango:ellipsize-mode (Read / Write)
Specifies the preferred place to ellipsize the string, if the cell renderer does not have enough room to display the entire string. Setting it to the :none value turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width.
Default value: :none
ellipsize-set
The ellipsize-set property of type :boolean (Read / Write)
Whether this tag affects the ellipsize mode.
Default value: false
family
The family property of type :string (Read / Write)
The name of the font family, for example, Sans, Helvetica, Times, Monospace.
Default value: nil
family-set
The family-set property of type :boolean (Read / Write)
Whether this tag affects the font family.
Default value: false
font
The font property of type :string (Read / Write)
The font description as a string, for example, "Sans Italic 12".
Default value: nil
font-desc
The font-desc property of type pango:font-description (Read / Write)
The Pango font description.
foreground
The foreground property of type :string (Write)
The foreground color as a string.
Default value: nil
foreground-rgba
The foreground-rgba property of type gdk:rgba (Read / Write)
The foreground color.
foreground-set
The foreground-set property of type :boolean (Read / Write)
Whether this tag affects the foreground color.
Default value: false
language
The language property of type :string (Read / Write)
The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If you do not understand this parameter, you probably do not need it.
Default value: nil
language-set
The language-set property of type :boolean (Read / Write)
Whether this tag affects the language the text is rendered as.
Default value: false
markup
The markup property of type :string (Write)
Marked up text to render.
The default value: nil
max-width-chars
The max-width-chars property of type :int (Read / Write)
The desired maximum width of the cell, in characters. If this property is set to -1, the width will be calculated automatically. For cell renderers that ellipsize or wrap text. This property controls the maximum reported width of the cell. The cell should not receive any greater allocation unless it is set to expand in its gtk:cell-layout object and all of the cell's siblings have received their natural width.
Allowed values: >= -1
Default value: -1
placeholder-text
The placeholder-text property of type :string (Read / Write)
The text that will be displayed in the gtk:cell-renderer object if the editable property is true and the cell is empty.
Default value: nil
rise
The rise property of type :int (Read / Write)
The offset of text above the baseline, below the baseline if this property is negative.
Allowed values: >= -2147483647
Default value: 0
rise-set
The rise-set property of type :boolean (Read / Write)
Whether this tag affects the rise.
Default value: false
scale
The scale property of type :double (Read / Write)
The font scaling factor.
Allowed values: >= 0
Default value: 1
scale-set
The scale-set property of type :boolean (Read / Write)
Whether this tag scales the font size by a factor.
Default value: false
single-paragraph-mode
The single-paragraph-mode property of type :boolean (Read / Write)
Whether to keep all text in a single paragraph.
Default value: false
size
The size property of type :int (Read / Write)
The font size.
Allowed values: >= 0
Default value: 0
size-points
The size-points property of type :double (Read / Write)
The font size in points.
Allowed values: >= 0
Default value: 0
size-set
The size-set property of type :boolean (Read / Write)
Whether this tag affects the font size.
Default value: false
stretch
The stretch property of type pango:stretch (Read / Write)
The font stretch.
Default value: :normal
stretch-set
The stretch-set property of type :boolean (Read / Write)
Whether this tag affects the font stretch.
Default value: false
strikethrough
The strikethrough property :boolean (Read / Write)
Whether to strike through the text.
Default value: false
strikethrough-set
The strikethrough-set property of type :boolean (Read / Write)
Whether this tag affects strikethrough.
Default value: false
style
The style property of type pango:style (Read / Write)
The font style.
Default value: :normal
style-set
The style-set property of type :boolean (Read / Write)
Whether this tag affects the font style.
Default value: false
text
The text property of type :string (Read / Write)
The text to render.
Default value: nil
underline
The underline property of type pango:underline (Read / Write)
The style of underline for this text.
Default value: :none
underline-set
The underline-set property of type :boolean (Read / Write)
Whether this tag affects underlining.
Default value: false
variant
The variant property of type pango:variant (Read / Write)
The font variant.
Default value: :normal
variant-set
The variant-set property of type :boolean (Read / Write)
Whether this tag affects the font variant.
Default value: false
weight
The weight property of type :int (Read / Write)
The font weight.
Allowed values: >= 0
Default value: 400
weight-set
The weight-set property of type :boolean (Read / Write)
Whether this tag affects the font weight.
Default value: false
width-chars
The width-chars property of type :int (Read / Write)
The desired width of the cell, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the cell will request either 3 characters or the property value, whichever is greater.
Allowed values: >= -1
Default value: -1
wrap-mode
The wrap-mode property of type pango:wrap-mode (Read / Write)
Specifies how to break the string into multiple lines, if the cell renderer does not have enough room to display the entire string. This property has no effect unless the wrap-width property is set.
Default value: :char
wrap-width
The wrap-width property of type :int (Read / Write)
Specifies the minimum width at which the text is wrapped. This property can be used to influence at what character positions the line breaks can be placed. Setting this property to -1 turns wrapping off.
Allowed values: >= -1
Default value: -1
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-text object renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the ellipsize property allows it. If the mode property is :editable, the gtk:cell-renderer-text object allows to edit its text using a gtk:entry widget.
Signal Details:
The "edited" signal
lambda (renderer path text)    :run-last      
renderer
The gtk:cell-renderer-text object which received the signal.
path
The string with the path identifying the edited cell.
text
The string with the new text.
The signal is emitted after renderer has been edited. It is the responsibility of the application to update the model and store text at the position indicated by path.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:inscription or gtk:label widgets instead.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-align-set (object)
Syntax:
(gtk:cell-renderer-text-align-set object) => align-set
(setf (gtk:cell-renderer-text-align-set object) align-set)
Arguments:
object -- a gtk:cell-renderer-text object
align-set -- a boolean whether this tag affects the alignment mode
Details:
Accessor of the align-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-alignment (object)
Syntax:
(gtk:cell-renderer-text-alignment object) => alignment
(setf (gtk:cell-renderer-text-alignment object) alignment)
Arguments:
object -- a gtk:cell-renderer-text object
alignment -- a pango:alignment value
Details:
Accessor of the alignment slot of the gtk:cell-renderer-text class. Specifies how to align the lines of text with respect to each other. Note that this property describes how to align the lines of text in case there are several of them. The xalign property, on the other hand, sets the horizontal alignment of the whole text.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-attributes (object)
Syntax:
(gtk:cell-renderer-text-attributes object) => attributes
(setf (gtk:cell-renderer-text-attributes object) attributes)
Arguments:
object -- a gtk:cell-renderer-text object
attributes -- a pango:attr-list instance
Details:
Accessor of the attributes slot of the gtk:cell-renderer-text class. A list of style attributes to apply to the text of the renderer.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-background (object)
Syntax:
(setf (gtk:cell-renderer-text-background object) background)
Arguments:
object -- a gtk:cell-renderer-text object
background -- a string with the background color
Details:
Accessor of the background slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-background-rgba (object)
Syntax:
(gtk:cell-renderer-text-background-rgba object) => background
(setf (gtk:cell-renderer-text-background-rgba object) background)
Arguments:
object -- a gtk:cell-renderer-text object
background -- a gdk:rgba instance with the background color
Details:
Accessor of the background-rgba slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-background-set (object)
Syntax:
(gtk:cell-renderer-text-background-set object) => setting
(setf (gtk:cell-renderer-text-background-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the background color
Details:
Accessor of the background-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-editable (object)
Syntax:
(gtk:cell-renderer-text-editable object) => setting
(setf (gtk:cell-renderer-text-editable object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether the text can be modified by the user
Details:
Accessor of the editable slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-editable-set (object)
Syntax:
(gtk:cell-renderer-text-editable-set object) => setting
(setf (gtk:cell-renderer-text-editable-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects text editability
Details:
Accessor of the editable-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-ellipsize (object)
Syntax:
(gtk:cell-renderer-text-ellipsize object) => mode
(setf (gtk:cell-renderer-text-ellipsize object) mode)
Arguments:
object -- a gtk:cell-renderer-text object
mode -- a pango:ellipsize-mode value
Details:
Accessor of the ellipsize slot of the gtk:cell-renderer-text class. Specifies the preferred place to ellipsize the string, if the cell renderer does not have enough room to display the entire string. Setting it to the :none value turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-ellipsize-set (object)
Syntax:
(gtk:cell-renderer-text-ellipsize-set object) => setting
(setf (gtk:cell-renderer-text-ellipsize-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the ellipsize mode
Details:
Accessor of the ellipsize-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-family (object)
Syntax:
(gtk:cell-renderer-text-family object) => font
(setf (gtk:cell-renderer-text-family object) font)
Arguments:
object -- a gtk:cell-renderer-text object
font -- a string with the name of the font family
Details:
Accessor of the family slot of the gtk:cell-renderer-text class. Name of the font family, for example, Sans, Helvetica, Times, Monospace.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-family-set (object)
Syntax:
(gtk:cell-renderer-text-family-set object) => setting
(setf (gtk:cell-renderer-text-family-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font family
Details:
Accessor of the family-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-font (object)
Syntax:
(gtk:cell-renderer-text-font object) => font
(setf (gtk:cell-renderer-text-font object) font)
Arguments:
object -- a gtk:cell-renderer-text object
font -- a string with the font description
Details:
Accessor of the font slot of the gtk:cell-renderer-text class. Font description as a string, for example "Sans Italic 12".
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-font-desc (object)
Syntax:
(gtk:cell-renderer-text-font-desc object) => font-desc
(setf (gtk:cell-renderer-text-font-desc object) font-desc)
Arguments:
object -- a gtk:cell-renderer-text object
font-desc -- a pango:font-description instance
Details:
Accessor of the font-desc slot of the gtk:cell-renderer-text class. A Pango font description.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-foreground (object)
Syntax:
(setf (gtk:cell-renderer-text-foreground object) foreground)
Arguments:
object -- a gtk:cell-renderer-text object
foreground -- a string with the foreground color
Details:
Accessor of the foreground slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-22
Accessor gtk:cell-renderer-text-foreground-rgba (object)
Syntax:
(gtk:cell-renderer-text-foreground-rgba object) => foreground
(setf (gtk:cell-renderer-text-foreground-rgba object) foreground)
Arguments:
object -- a gtk:cell-renderer-text object
foreground -- a gdk:rgba instance
Details:
Accessor of the foreground-rgba slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-foreground-set (object)
Syntax:
(gtk:cell-renderer-text-foreground-set object) => setting
(setf (gtk:cell-renderer-text-foreground-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the foreground color
Details:
Accessor of the foreground-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-language (object)
Syntax:
(gtk:cell-renderer-text-language object) => language
(setf (gtk:cell-renderer-text-language object) language)
Arguments:
object -- a gtk:cell-renderer-text object
language -- a string with the language this text is in
Details:
Accessor of the language slot of the gtk:cell-renderer-text class. The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If you do not understand this parameter, you probably do not need it.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-language-set (object)
Syntax:
(gtk:cell-renderer-text-language-set object) => setting
(setf (gtk:cell-renderer-text-language-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the language
Details:
Accessor of the language-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-markup (object)
Syntax:
(setf (gtk:cell-renderer-text-markup object) markup)
Arguments:
object -- a gtk:cell-renderer-text object
markup -- a string with the marked up text to render
Details:
Accessor of the markup slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-max-width-chars (object)
Syntax:
(gtk:cell-renderer-text-max-width-chars object) => width
(setf (gtk:cell-renderer-text-max-width-chars object) width)
Arguments:
object -- a gtk:cell-renderer-text object
width -- an integer with the maximum width of the cell
Details:
Accessor of the max-width-chars slot of the gtk:cell-renderer-text class. The desired maximum width of the cell, in characters. If this property is set to -1, the width will be calculated automatically. For cell renderers that ellipsize or wrap text. This property controls the maximum reported width of the cell. The cell should not receive any greater allocation unless it is set to expand in its gtk:cell-layout object and all of the cell's siblings have received their natural width.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-placeholder-text (object)
Syntax:
(gtk:cell-renderer-text-placeholder-text object) => text
(setf (gtk:cell-renderer-text-placeholder-text object) text)
Arguments:
object -- a gtk:cell-renderer-text object
text -- a string with the placeholder text
Details:
Accessor of the placeholder-text slot of the gtk:cell-renderer-text class. The text that will be displayed in the gtk:cell-renderer object if the editable property is true and the cell is empty.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-rise (object)
Syntax:
(gtk:cell-renderer-text-rise object) => rise
(setf (gtk:cell-renderer-text-rise object) rise)
Arguments:
object -- a gtk:cell-renderer-text object
rise -- an integer with the offset of text above the baseline
Details:
Accessor of the rise slot of the gtk:cell-renderer-text class. Offset of text above the baseline, below the baseline if the rise property is negative.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-rise-set (object)
Syntax:
(gtk:cell-renderer-text-rise-set object) => setting
(setf (gtk:cell-renderer-text-rise-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the rise
Details:
Accessor of the rise-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-scale (object)
Syntax:
(gtk:cell-renderer-text-scale object) => scale
(setf (gtk:cell-renderer-text-scale object) scale)
Arguments:
object -- a gtk:cell-renderer-text object
scale -- a double float with the font scaling factor
Details:
Accessor of the scale slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-scale-set (object)
Syntax:
(gtk:cell-renderer-text-scale-set object) => setting
(setf (gtk:cell-renderer-text-scale-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag scales the font size by a factor
Details:
Accessor of the scale-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-single-paragraph-mode (object)
Syntax:
(gtk:cell-renderer-text-single-paragraph-mode object) => mode
(setf (gtk:cell-renderer-text-single-paragraph-mode object) mode)
Arguments:
object -- a gtk:cell-renderer-text object
mode -- a boolean whether to keep all text in a single paragraph
Details:
Accessor of the single-paragraph-mode slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-size (object)
Syntax:
(gtk:cell-renderer-text-size object) => size
(setf (gtk:cell-renderer-text-size object) size)
Arguments:
object -- a gtk:cell-renderer-text object
size -- an integer with the font size
Details:
Accessor of the size slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-size-points (object)
Syntax:
(gtk:cell-renderer-text-size-points object) => size
(setf (gtk:cell-renderer-text-size-points object) size)
Arguments:
object -- a gtk:cell-renderer-text object
size -- a double float with the font size in points
Details:
Accessor of the size-points slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-size-set (object)
Syntax:
(gtk:cell-renderer-text-size-set object) => setting
(setf (gtk:cell-renderer-text-size-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font size
Details:
Accessor of the size-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-stretch (object)
Syntax:
(gtk:cell-renderer-text-stretch object) => stretch
(setf (gtk:cell-renderer-text-stretch object) stretch)
Arguments:
object -- a gtk:cell-renderer-text object
stretch -- a pango:stretch value with the font stretch
Details:
Accessor of the stretch slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-stretch-set (object)
Syntax:
(gtk:cell-renderer-text-stretch-set object) => setting
(setf (gtk:cell-renderer-text-stretch-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font stretch
Details:
Accessor of the stretch-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-strikethrough (object)
Syntax:
(gtk:cell-renderer-text-strikethrough object) => setting
(setf (gtk:cell-renderer-text-strikethrough object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether to strike through the text
Details:
Accessor of the strikethrough slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-strikethrough-set (object)
Syntax:
(gtk:cell-renderer-text-strikethrough-set object) => setting
(setf (gtk:cell-renderer-text-strikethrough-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects strikethrough
Details:
Accessor of the strikethrough-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-style (object)
Syntax:
(gtk:cell-renderer-text-style object) => style
(setf (gtk:cell-renderer-text-style object) style)
Arguments:
object -- a gtk:cell-renderer-text object
style -- a pango:style value with the font style
Details:
Accessor of the style slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-style-set (object)
Syntax:
(gtk:cell-renderer-text-style-set object) => setting
(setf (gtk:cell-renderer-text-style-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font style
Details:
Accessor of the style-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-text (object)
Syntax:
(gtk:cell-renderer-text-text object) => text
(setf (gtk:cell-renderer-text-text object) text)
Arguments:
object -- a gtk:cell-renderer-text object
text -- a string with the text to render
Details:
Accessor of the text slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-underline (object)
Syntax:
(gtk:cell-renderer-text-underline object) => underline
(setf (gtk:cell-renderer-text-underline object) underline)
Arguments:
object -- a gtk:cell-renderer-text object
underline -- a pango:underline value with the style of underline for this text
Details:
Accessor of the underline slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-underline-set (object)
Syntax:
(gtk:cell-renderer-text-underline-set object) => setting
(setf (gtk:cell-renderer-text-underline-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects underlining
Details:
Accessor of the underline-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-variant (object)
Syntax:
(gtk:cell-renderer-text-variant object) => variant
(setf (gtk:cell-renderer-text-variant object) variant)
Arguments:
object -- a gtk:cell-renderer-text object
variant -- a pango:variant value with the font variant
Details:
Accessor of the variant slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-variant-set (object)
Syntax:
(gtk:cell-renderer-text-variant-set object) => setting
(setf (gtk:cell-renderer-text-variant-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font variant
Details:
Accessor of the variant-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-weight (object)
Syntax:
(gtk:cell-renderer-text-weight object) => weight
(setf (gtk:cell-renderer-text-weight object) weight)
Arguments:
object -- a gtk:cell-renderer-text object
weight -- an integer with the font weight
Details:
Accessor of the weight slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-weight-set (object)
Syntax:
(gtk:cell-renderer-text-weight-set object) => setting
(setf (gtk:cell-renderer-text-weight-set object) setting)
Arguments:
object -- a gtk:cell-renderer-text object
setting -- a boolean whether this tag affects the font weight
Details:
Accessor of the weight-set slot of the gtk:cell-renderer-text class.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-width-chars (object)
Syntax:
(gtk:cell-renderer-text-width-chars object) => width
(setf (gtk:cell-renderer-text-width-chars object) width)
Arguments:
object -- a gtk:cell-renderer-text object
width -- an integer with the width of the cell
Details:
Accessor of the width-chars slot of the gtk:cell-renderer-text class. The desired width of the cell, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the cell will request either 3 characters or the property value, whichever is greater.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-wrap-mode (object)
Syntax:
(gtk:cell-renderer-text-wrap-mode object) => mode
(setf (gtk:cell-renderer-text-wrap-mode object) mode)
Arguments:
object -- a gtk:cell-renderer-text object
mode -- a pango:wrap-mode value
Details:
Accessor of the wrap-mode slot of the gtk:cell-renderer-text class. Specifies how to break the string into multiple lines, if the cell renderer does not have enough room to display the entire string. This property has no effect unless the wrap-width property is set.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-text-wrap-width (object)
Syntax:
(gtk:cell-renderer-text-wrap-width object) => width
(setf (gtk:cell-renderer-text-wrap-width object) width)
Arguments:
object -- a gtk:cell-renderer-text object
width -- an integer with the minimum width at which text is wrapped
Details:
Accessor of the wrap-width slot of the gtk:cell-renderer-text class. Specifies the minimum width at which the text is wrapped. The wrap-mode property can be used to influence at what character positions the line breaks can be placed. Setting the width argument to -1 turns wrapping off.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Function gtk:cell-renderer-text-new ()
Returns:
The new gtk:cell-renderer-text object.
Details:
Creates a new cell renderer text. Adjust how text is drawn using object properties. Object properties can be set globally, with the g:object-property function. Also, with the gtk:tree-view-column object, you can bind a property to a value in a gtk:tree-model object. For example, you can bind the text property on the cell renderer to a string value in the model, thus rendering a different string in each row of the gtk:tree-view widget.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Function gtk:cell-renderer-text-set-fixed-height-from-font (renderer number-of-rows)
Arguments:
renderer -- a gtk:cell-renderer-text object
number-of-rows -- an integer with the number of rows of text each cell renderer is allocated, or -1
Details:
Sets the height of a renderer to explicitly be determined by the font and y-pad properties set on it. Further changes in these properties do not affect the height, so they must be accompanied by a subsequent call to this function. Using this function is unflexible, and should really only be used if calculating the size of a cell is too slow, that is, a massive number of cells displayed. If the number-of-rows argument is -1, then the fixed height is unset, and the height is determined by the properties again.
Warning:
The gtk:cell-renderer-text implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2024-2-21

GtkCellRendererAccel

GEnum gtk:cell-renderer-accel-mode
Declaration:
(gobject:define-genum "GtkCellRendererAccelMode" cell-renderer-accel-mode
  (:export t
   :type-initializer "gtk_cell_renderer_accel_mode_get_type")
  (:gtk 0)
  (:other 1))  
Values:
:gtk
GTK accelerators mode.
:other
Other accelerator mode.
Details:
Determines if the edited accelerators are GTK accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus.
See also:
2024-2-21
Class gtk:cell-renderer-accel
Superclasses:
Documented Subclasses:
None
Direct Slots:
accel-key
The accel-key property of type :uint (Read / Write)
The keyval of the accelerator.
Allowed values: <= G_MAXINT
Default value: 0
accel-mode
The accel-mode property of type gtk:cell-renderer-accel-mode (Read / Write)
Determines if the edited accelerators are GTK accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus.
Default value: :gtk
accel-mods
The accel-mods property of type gdk:modifier-type (Read / Write)
The modifier mask of the accelerator.
keycode
The keycode property of type :uint (Read / Write)
The hardware keycode of the accelerator. Note that the hardware keycode is only relevant if the key does not have a keyval. Normally, the keyboard configuration should assign keyvals to all keys.
Allowed values: <= G_MAXINT
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-accel object displays a keyboard accelerator, that is a key combination like Control+a. If the cell renderer is editable, the accelerator can be changed by simply typing the new combination.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Applications editing keyboard accelerators should provide their own implementation according to platform design guidelines.
Signal Details:
The "accel-cleared" signal
lambda (accel path)    :run-last      
accel
The gtk:cell-renderer-accel object reveiving the signal.
path
The string with the path identifying the row of the edited cell.
Gets emitted when the user has removed the accelerator.
The "accel-edited" signal
lambda (accel path key mods keycode)    :run-last      
accel
The gtk:cell-renderer-accel object reveiving the signal.
path
The string with the path identifying the row of the edited cell.
key
The unsigned integer with the new accelerator keyval.
mods
The gdk:modifier-type value with the new acclerator modifier mask.
keycode
The unsigned integer with the keycode of the new accelerator.
Gets emitted when the user has selected a new accelerator.
See also:
2024-7-30
Accessor gtk:cell-renderer-accel-accel-key (object)
Syntax:
(gtk:cell-renderer-accel-accel-key object) => key
(setf (gtk:cell-renderer-accel-accel-key object) key)
Arguments:
object -- a gtk:cell-renderer-accel object
key -- an unsigned integer with the keyval of the accelerator
Details:
Accessor of the accel-key slot of the gtk:cell-renderer-accel class.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-accel-accel-mode (object)
Syntax:
(gtk:cell-renderer-accel-accel-mode object) => mode
(setf (gtk:cell-renderer-accel-accel-mode object) mode)
Arguments:
object -- a gtk:cell-renderer-accel object
Details:
Accessor of the accel-mode slot of the gtk:cell-renderer-accel class. Determines if the edited accelerators are GTK accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-accel-accel-mods (object)
Syntax:
(gtk:cell-renderer-accel-accel-mods object) => accel-mods
(setf (gtk:cell-renderer-accel-accel-mods object) accel-mods)
Arguments:
object -- a gtk:cell-renderer-accel object
accel-mode -- a gdk:modifier-type value with the modifier mask of the accelerator
Details:
Accessor of the accel-mods slot of the gtk:cell-renderer-accel class.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-accel-keycode (object)
Syntax:
(gtk:cell-renderer-accel-keycode object) => keycode
(setf (gtk:cell-renderer-accel-keycode object) keycode)
Arguments:
object -- a gtk:cell-renderer-accel object
keycode -- an unsigned integer with the hardware keycode of the accelerator
Details:
Accessor of the keycode slot of the gtk:cell-renderer-accel class. The hardware keycode of the accelerator. Note that the hardware keycode is only relevant if the key does not have a keyval. Normally, the keyboard configuration should assign keyvals to all keys.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Function gtk:cell-renderer-accel-new ()
Returns:
The new gtk:cell-renderer-accel object.
Details:
Creates a new cell renderer accel object.
Warning:
The gtk:cell-renderer-accel implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21

GtkCellRendererCombo

Class gtk:cell-renderer-combo
Superclasses:
Documented Subclasses:
None
Direct Slots:
has-entry
The has-entry property of type :boolean (Read / Write)
If true, the cell renderer will include an entry and allow to enter values other than the ones in the popup list.
Default value: true
model
The model property of type gtk:tree-model (Read / Write)
Holds a tree model containing the possible values for the combo box. Use the text-column property to specify the column holding the values.
text-column
The text-column property of type :int (Read / Write)
Specifies the model column which holds the possible values for the combo box. Note that this refers to the model specified in the model property, not the model backing the tree view to which this cell renderer is attached. The combo cell renderer automatically adds a text cell renderer for this column to its combo box.
Allowed values: >= -1
Default value: -1
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-combo object renders text in a cell like the gtk:cell-renderer-text object from which it is derived. But while the gtk:cell-renderer-text object offers a simple entry to edit the text, the gtk:cell-renderer-combo object offers a gtk:combo-box widget to edit the text. The values to display in the combo box are taken from the tree model specified in the model property.

The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its text-column property. Further properties of the combo box can be set in a handler for the "editing-started" signal.
Warning:
The gtk:cell-renderer-combo object is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:drop-down widget instead.
Signal Details:
The "changed" signal
lambda (combo path iter)    :run-last      
combo
The gtk:cell-renderer-combo object on which the signal is emitted.
path
The string of the path identifying the edited cell, relative to the tree view model.
iter
The gtk:tree-iter instance selected in the combo box, relative to the combo box model.
The signal is emitted each time after the user selected an item in the combo box, either by using the mouse or the arrow keys. Contrary to the gtk:combo-box widget, the "changed" signal is not emitted for changes made to a selected item in the text entry. The iter argument corresponds to the newly selected item in the combo box and it is relative to the gtk:tree-model object set via the model property on the gtk:cell-renderer-combo object. Note that as soon as you change the model displayed in the tree view, the tree view will immediately cease the editing operating. This means that you most probably want to refrain from changing the model until the combo cell renderer emits the edited or "editing-canceled" signal.
See also:
2024-2-21
Accessor gtk:cell-renderer-combo-has-entry (object)
Syntax:
(gtk:cell-renderer-combo-has-entry object) => has-entry
(setf (gtk:cell-renderer-combo-has-entry object) has-entry)
Arguments:
object -- a gtk:cell-renderer-combo object
has-entry -- a boolean whether the cell renderer will include an entry
Details:
Accessor of the has-entry slot of the gtk:cell-renderer-combo class. If true, the cell renderer will include an entry and allow to enter values other than the ones in the popup list.
Warning:
The gtk:cell-renderer-combo object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-combo-model (object)
Syntax:
(gtk:cell-renderer-combo-model object) => model
(setf (gtk:cell-renderer-combo-model object) model)
Arguments:
object -- a gtk:cell-renderer-combo object
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:cell-renderer-combo class. Holds a tree model containing the possible values for the combo box. Use the text-column property to specify the column holding the values.
Warning:
The gtk:cell-renderer-combo object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-combo-text-column (object)
Syntax:
(gtk:cell-renderer-combo-text-column object) => column
(setf (gtk:cell-renderer-combo-text-column object) column)
Arguments:
object -- a gtk:cell-renderer-combo object
column -- an integer which specifies the model colum which holds the possible values for the combo box
Details:
Accessor of the text-column slot of the gtk:cell-renderer-combo class. Specifies the model column which holds the possible values for the combo box. Note that this refers to the model specified in the model property, not the model backing the tree view to which this cell renderer is attached. The combo cell renderer automatically adds a text cell renderer for this column to its combo box.
Warning:
The gtk:cell-renderer-combo implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Function gtk:cell-renderer-combo-new ()
Returns:
The new gtk:cell-renderer-combo object.
Details:
Creates a new cell renderer combo. Adjust how text is drawn using object properties. Object properties can be set globally, with the g:object-property function. Also, with the gtk:tree-view-column object, you can bind a property to a value in a gtk:tree-model object. For example, you can bind the text property on the cell renderer to a string value in the model, thus rendering a different string in each row of the gtk:tree-view widget.
Warning:
The gtk:cell-renderer-combo object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21

GtkCellRendererPixbuf

Class gtk:cell-renderer-pixbuf
Superclasses:
gtk:cell-renderer, gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
gicon
The gicon property of type g:icon (Read / Write)
Represents the icon to display. If the icon theme is changed, the image will be updated automatically.
icon-name
The icon-name property of type :string (Read / Write)
The name of the themed icon to display. This property only has an effect if not overridden by the pixbuf property.
Default value: nil
icon-size
The icon-size property of type gtk:icon-size (Read / Write)
Specifies the icon size of the rendered icon.
Default value: :inherit
pixbuf
The pixbuf property of type gdk-pixbuf:pixbuf (Write)
The pixbuf to render.
pixbuf-expander-closed
The pixbuf-expander-closed property of type gdk-pixbuf:pixbuf (Read / Write)
The pixbuf for the closed expander.
pixbuf-expander-open
The pixbuf-expander-open property of type gdk-pixbuf:pixbuf (Read / Write)
The pixbuf for the open expander.
texture
The texture property of type gdk:texture (Read / Write)
The texture to render.
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-pixbuf object can be used to render an image in a cell. It allows to render either a given gdk-pixbuf:pixbuf object, set via the pixbuf property, or a named icon, set via the icon-name property.

To support the tree view, the gtk:cell-renderer-pixbuf object also supports rendering two alternative pixbufs, when the is-expander property is true. If the is-expanded property is true and the pixbuf-expander-open property is set to a pixbuf, it renders that pixbuf, if the is-expanded property is false and the pixbuf-expander-closed property is set to a pixbuf, it renders that one.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:image widget for icons, and the gtk:picture widget for images.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-gicon (object)
Syntax:
(gtk:cell-renderer-pixbuf-gicon object) => icon
(setf (gtk:cell-renderer-pixbuf-gicon object) icon)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
icon -- a g:icon object
Details:
Accessor of the gicon slot of the gtk:cell-renderer-pixbuf class. The g:icon object representing the icon to display. If the icon theme is changed, the image will be updated automatically.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-icon-name (object)
Syntax:
(gtk:cell-renderer-pixbuf-icon-name object) => name
(setf (gtk:cell-renderer-pixbuf-icon-name object) name)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
name -- a string with the name of the themed icon to display
Details:
Accessor of the icon-name slot of the gtk:cell-renderer-pixbuf class. The name of the themed icon to display. This property only has an effect if not overridden by the pixbuf property.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-icon-size (object)
Syntax:
(gtk:cell-renderer-pixbuf-icon-size object) => size
(setf (gtk:cell-renderer-pixbuf-icon-size object) size)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
size -- a gtk:icon-size value
Details:
Accessor of the icon-size slot of the gtk:cell-renderer-pixbuf class. The gtk:icon-size value that specifies the size of the rendered icon.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-pixbuf (object)
Syntax:
(setf (gtk:cell-renderer-pixbuf-pixbuf object) pixbuf)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
pixbuf -- a gdk-pixbuf:pixbuf object
Details:
Accessor of the pixbuf slot of the gtk:cell-renderer-pixbuf class.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-pixbuf-expander-closed (object)
Syntax:
(gtk:cell-renderer-pixbuf-pixbuf-expander-closed object) => pixbuf
(setf (gtk:cell-renderer-pixbuf-pixbuf-expander-closed object) pixbuf)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
pixbuf -- a gdk-pixbuf:pixbuf object
Details:
Accessor of the pixbuf-expander-closed slot of the gtk:cell-renderer-pixbuf class.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Accessor gtk:cell-renderer-pixbuf-pixbuf-expander-open (object)
Syntax:
(gtk:cell-renderer-pixbuf-pixbuf-expander-open object) => pixbuf
(setf (gtk:cell-renderer-pixbuf-pixbuf-expander-open object) pixbuf)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
pixbuf -- a gdk-pixbuf:pixbuf object
Details:
Accessor of the pixbuf-expander-open slot of the gtk:cell-renderer-pixbuf class.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Generic Function gtk:cell-renderer-pixbuf-texture (object)
Syntax:
(gtk:cell-renderer-pixbuf-texture object) => texture
(setf (gtk:cell-renderer-pixbuf-texture object) texture)
Arguments:
object -- a gtk:cell-renderer-pixbuf object
texture -- a gdk:texture instance to render
Details:
Accessor of the texture slot of the gtk:cell-renderer-pixbuf class.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16
Function gtk:cell-renderer-pixbuf-new ()
Returns:
The new gtk:cell-renderer-pixbuf object.
Details:
Creates a new cell renderer pixbuf. Adjust rendering parameters using object properties. Object properties can be set globally with the g:object-property function. Also, with the gtk:tree-view-column widget, you can bind a property to a value in a gtk:tree-model widget. For example, you can bind the pixbuf property on the cell renderer to a pixbuf value in the model, thus rendering a different image in each row of the gtk:tree-view widget.
Warning:
The gtk:cell-renderer-pixbuf implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-5-16

GtkCellRendererProgress

Class gtk:cell-renderer-progress
Superclasses:
gtk:cell-renderer, gobject:initially-unowned, gtk:orientable, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
inverted
The inverted property of type :boolean (Read / Write)
Invert the direction in which the progress bar grows.
Default value: false
pulse
The pulse property of type :int (Read / Write)
Setting this to a non-negative value causes the cell renderer to enter "activity mode", where a block bounces back and forth to indicate that some progress is made, without specifying exactly how much. Each increment of the property causes the block to move by a little bit. To indicate that the activity has not started yet, set the property to zero. To indicate completion, set the property to G_MAXINT.
Allowed values: >= -1
Default value: -1
text
The text property of type :string (Read / Write)
Determines the label which will be drawn over the progress bar. Setting this property to nil causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed.
Default value: nil
text-xalign
The text-xalign property of type :float (Read / Write)
Controls the horizontal alignment of the text in the progress bar. Valid values range from 0.0 (left) to 1.0 (right). Reserved for RTL layouts.
Allowed values: [0.0, 1.0]
Default value: 0.5
text-yalign
The text-yalign property of type :float (Read / Write)
Controls the vertical alignment of the text in the progress bar. Valid values range from 0.0 (top) to 1.0 (bottom).
Allowed values: [0.0, 1.0]
Default value: 0.5
value
The value property of type :int (Read / Write)
Determines the percentage to which the progress bar will be "filled in".
Allowed values: [0,100]
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-progress object renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:progress-bar widget instead.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-inverted (object)
Syntax:
(gtk:cell-renderer-progress-inverted object) => setting
(setf (gtk:cell-renderer-progress-inverted object) setting)
Arguments:
object -- a gtk:cell-renderer-progress object
setting -- a boolean whether to invert the direction in which the progress bar grows
Details:
Accessor of the inverted slot of the gtk:cell-renderer-progress class.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-pulse (object)
Syntax:
(gtk:cell-renderer-progress-pulse object) => pulse
(setf (gtk:cell-renderer-progress-pulse object) pulse)
Arguments:
object -- a gtk:cell-renderer-progress object
pulse -- an integer for the pulse value
Details:
Accessor of the pulse slot of the gtk:cell-renderer-progress class. Setting this to a non-negative value causes the cell renderer to enter "activity mode", where a block bounces back and forth to indicate that some progress is made, without specifying exactly how much. Each increment of the property causes the block to move by a little bit. To indicate that the activity has not started yet, set the property to zero. To indicate completion, set the property to G_MAXINT.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-text (object)
Syntax:
(gtk:cell-renderer-progress-text object) => text
(setf (gtk:cell-renderer-progress-text object) text)
Arguments:
object -- a gtk:cell-renderer-progress object
text -- a string for the label which will be drawn over the progress bar
Details:
Accessor of the text slot of the gtk:cell-renderer-progress class. Determines the label which will be drawn over the progress bar. Setting this property to nil causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-text-xalign (object)
Syntax:
(gtk:cell-renderer-progress-text-xalign object) => align
(setf (gtk:cell-renderer-progress-text-xalign object) align)
Arguments:
object -- a gtk:cell-renderer-progress object
align -- a single float which controls the horizontal alignment
Details:
Accessor of the text-xalign slot of the gtk:cell-renderer-progress class. Controls the horizontal alignment of the text in the progress bar. Valid values range from 0.0 (left) to 1.0 (right). Reserved for RTL layouts.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-text-yalign (object)
Syntax:
(gtk:cell-renderer-progress-text-yalign object) => align
(setf (gtk:cell-renderer-progress-text-yalign object) align)
Arguments:
object -- a gtk:cell-renderer-progress object
align -- a single float which controls the vertical alignment
Details:
Accessor of the text-yalign slot of the gtk:cell-renderer-progress class. Controls the vertical alignment of the text in the progress bar. Valid values range from 0.0 (top) to 1.0 (bottom).
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Accessor gtk:cell-renderer-progress-value (object)
Syntax:
(gtk:cell-renderer-progress-value object) => value
(setf (gtk:cell-renderer-progress-value object) value)
Arguments:
object -- a gtk:cell-renderer-progress object
value -- an integer which determines the percentage the progress bar will be filled in
Details:
Accessor of the value slot of the gtk:cell-renderer-progress class. Determines the percentage to which the progress bar will be "filled in".
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21
Function gtk:cell-renderer-progress-new ()
Returns:
Details:
Creates a new cell renderer progress object.
Warning:
The gtk:cell-renderer-progress implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-21

GtkCellRendererSpin

Class gtk:cell-renderer-spin
Superclasses:
Documented Subclasses:
None
Direct Slots:
adjustment
The adjustment property of type gtk:adjustment (Read / Write)
The adjustment that holds the value of the spin button. This must be non-nil for the cell renderer to be editable.
climb-rate
The climb-rate property of type :double (Read / Write)
The acceleration rate when you hold down a button.
Allowed values: >= 0
Default value: 0
digits
The digits property of type :uint (Read / Write)
The number of decimal places to display.
Allowed values: <= 20
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-spin object renders text in a cell like gtk:cell-renderer-text object from which it is derived. But while the gtk:cell-renderer-text object offers a simple entry to edit the text, the gtk:cell-renderer-spin object offers a gtk:spin-button widget. Of course, that means that the text has to be parseable as a floating point number.

The range of the spin button is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. The gtk:cell-renderer-spin object also has the climb-rate and digits properties. Other gtk:spin-button properties can be set in a handler for the "editing-started" signal.
Warning:
The gtk:cell-renderer-spin object is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:spin-button widget instead.
See also:
2024-2-22
Accessor gtk:cell-renderer-spin-adjustment (object)
Syntax:
(gtk:cell-renderer-spin-adjustment object) => adjustment
(setf (gtk:cell-renderer-spin-adjustment object) adjustment)
Arguments:
object -- a gtk:cell-renderer-spin object
adjustment -- a gtk:adjustment object
Details:
Accessor of the adjustment slot of the gtk:cell-renderer-spin class. The adjustment that holds the value of the spin button. This must be non-nil for the cell renderer to be editable.
Warning:
The gtk:cell-renderer-spin object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Accessor gtk:cell-renderer-spin-climb-rate (object)
Syntax:
(gtk:cell-renderer-spin-climb-rate object) => climb-rate
(setf (gtk:cell-renderer-spin-climb-rate object) climb-rate)
Arguments:
object -- a gtk:cell-renderer-spin object
climb-rate -- a double float with the acceleration rate
Details:
Accessor of the climb-rate slot of the gtk:cell-renderer-spin class.
Warning:
The gtk:cell-renderer-spin object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Accessor gtk:cell-renderer-spin-digits (object)
Syntax:
(gtk:cell-renderer-spin-digits object) => digits
(setf (gtk:cell-renderer-spin-digits object) digits)
Arguments:
object -- a gtk:cell-renderer-spin object
digits -- an unsigned integer with the number of decimal places to display
Details:
Accessor of the digits slot of the gtk:cell-renderer-spin class.
Warning:
The gtk:cell-renderer-spin object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Function gtk:cell-renderer-spin-new ()
Returns:
The new gtk:cell-renderer-spin object.
Details:
Creates a new cell renderer spin object.
Warning:
The gtk:cell-renderer-spin object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22

GtkCellRendererToggle

Class gtk:cell-renderer-toggle
Superclasses:
gtk:cell-renderer, gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
activatable
The activatable property of type :boolean (Read / Write)
Whether the toggle button can be activated.
Default value: true
active
The active property of type :boolean (Read / Write)
The toggle state of the button.
Default value: false
inconsistent
The inconsistent property of type :boolean (Read / Write)
The inconsistent state of the button.
Default value: false
radio
The radio property of type :boolean (Read / Write)
Draw the toggle button as a radio button.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-toggle object renders a toggle button in a cell. The button is drawn as a radio button or a check button, depending on the radio property. When activated, it emits the "toggled" signal.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:toggle-button widget instead.
Signal Details:
The "toggled" signal
lambda (renderer path)    :run-last      
renderer
The gtk:cell-renderer-toggle object which received the signal.
path
String representation of the gtk:tree-path instance describing the event location.
The signal is emitted when the cell is toggled.
See also:
2024-2-22
Accessor gtk:cell-renderer-toggle-activatable (object)
Syntax:
(gtk:cell-renderer-toggle-activatable object) => setting
(setf (gtk:cell-renderer-toggle-activatable object) setting)
Arguments:
toggle -- a gtk:cell-renderer-toggle object
setting -- a boolean value to set
Details:
Accessor of the activatable slot of the gtk:cell-renderer-toggle class. The gtk:cell-renderer-toggle-activatable function returns whether the cell renderer is activatable. The (setf gtk:cell-renderer-toggle-activatable) function makes the cell renderer activatable.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Accessor gtk:cell-renderer-toggle-active (object)
Syntax:
(gtk:cell-renderer-toggle-active object) => setting
(setf (gtk:cell-renderer-toggle-active object) setting)
Arguments:
toggle -- a gtk:cell-renderer-toggle object
setting -- a boolean value to set
Details:
Accessor of the active slot of the gtk:cell-renderer-toggle class. The gtk:cell-renderer-toggle-active function returns whether the cell renderer is active. The (setf gtk:cell-renderer-toggle-active) function activates or deactivates a cell renderer.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Accessor gtk:cell-renderer-toggle-inconsistent (object)
Syntax:
(gtk:cell-renderer-toggle-inconsistent object) => setting
(setf (gtk:cell-renderer-toggle-inconsistent object) setting)
Arguments:
toggle -- a gtk:cell-renderer-toggle object
setting -- a boolean value to set
Details:
Accessor of the inconsistent slot of the gtk:cell-renderer-toggle class. The inconsistent state of the button.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Accessor gtk:cell-renderer-toggle-radio (object)
Syntax:
(gtk:cell-renderer-toggle-radio object) => radio
(setf (gtk:cell-renderer-toggle-radio object) radio)
Arguments:
toggle -- a gtk:cell-renderer-toggle object
radio -- true to make the toggle look like a radio button
Details:
Accessor of the radio slot of the gtk:cell-renderer-toggle class. If the radio argument is true, the cell renderer renders a radio toggle, that is, a toggle in a group of mutually-exclusive toggles. If false, it renders a check toggle, a standalone boolean option.

This can be set globally for the cell renderer, or changed just before rendering each cell in the model, for the gtk:tree-view widget, you set up a per-row setting using a gtk:tree-view-column object to associate model columns with cell renderer properties.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-7-30
Function gtk:cell-renderer-toggle-new ()
Returns:
The new gtk:cell-renderer-toggle object.
Details:
Creates a new cell renderer toggle. Adjust rendering parameters using object properties. Object properties can be set globally, with the g:object-property function. Also, with the gtk:tree-view-column object, you can bind a property to a value in a gtk:tree-model object. For example, you can bind the active property on the cell renderer to a boolean value in the model, thus causing the check button to reflect the state of the model.
Warning:
The gtk:cell-renderer-toggle object is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22

GtkCellRendererSpinner

Class gtk:cell-renderer-spinner
Superclasses:
gtk:cell-renderer, gobject:initially-unowned, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
active
The active property of type :boolean (Read / Write)
Whether the spinner is active, that is, shown in the cell.
Default value: false
pulse
The pulse property of type :uint (Read / Write)
The pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the gtk:spinner widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds.
Default value: 0
size
The size property of type gtk:icon-size (Read / Write)
The icon size that specifies the size of the rendered spinner.
Default value: :menu
Returned by:
Slot Access Functions:
Details:
The gtk:cell-renderer-spinner class renders a spinning animation in a cell, very similar to the gtk:spinner widget. It can often be used as an alternative to a the gtk:cell-renderer-progress object for displaying indefinite activity, instead of actual progress.

To start the animation in a cell, set the active property to true and increment the pulse property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using, for example, the gtk:tree-view-column-add-attribute function.
Warning:
The gtk:cell-renderer-spinner implementation is deprecated since 4.10. List views use widgets to display their contents. You should use the gtk:spinner widget instead.
See also:
2024-7-30
Accessor gtk:cell-renderer-spinner-active (object)
Syntax:
(gtk:cell-renderer-spinner-active object) => active
(setf (gtk:cell-renderer-spinner-active object) active)
Arguments:
object -- a gtk:cell-renderer-spinner object
active -- a boolean whether the spinner is active
Details:
Accessor of the active slot of the gtk:cell-renderer-spinner class. Whether the spinner is active, that is, shown in the cell.
Warning:
The gtk:cell-renderer-spinner implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-7-30
Accessor gtk:cell-renderer-spinner-pulse (object)
Syntax:
(gtk:cell-renderer-spinner-pulse object) => pulse
(setf (gtk:cell-renderer-spinner-pulse object) pulse)
Arguments:
object -- a gtk:cell-renderer-spinner object
pulse -- an unsigned integer with the pulse of the spinner
Details:
Accessor of the pulse slot of the gtk:cell-renderer-spinner class. The pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the gtk:spinner widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds.
Warning:
The gtk:cell-renderer-spinner implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-7-30
Accessor gtk:cell-renderer-spinner-size (object)
Syntax:
(gtk:cell-renderer-spinner-size object) => size
(setf (gtk:cell-renderer-spinner-size object) size)
Arguments:
object -- a gtk:cell-renderer-spinner object
size -- a gtk:icon-size value
Details:
Accessor of the size slot of the gtk:cell-renderer-spinner class. The icon size that specifies the size of the rendered spinner.
Warning:
The gtk:cell-renderer-spinner implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22
Function gtk:cell-renderer-spinner-new ()
Returns:
Details:
Returns a new cell renderer which will show a spinner to indicate activity.
Warning:
The gtk:cell-renderer-spinner implementation is deprecated since 4.10. Please do not use it in newly written code.
See also:
2024-2-22

GtkListStore

Class gtk:list-store
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:list-store object is a list model for use with a gtk:tree-view widget. It implements the gtk:tree-model interface, and consequentialy, can use all of the methods available there. It also implements the gtk:tree-sortable interface so it can be sorted by the tree view. Finally, it also implements the tree drag and drop interfaces.

The gtk:list-store object can accept most GObject types as a column type, though it cannot accept all custom types. Internally, it will keep a copy of data passed in, such as a string or a boxed pointer. Columns that accept GObjects are handled a little differently. The gtk:list-store object will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call the gtk:tree-model-row-changed function to emit the "row-changed" signal. This most commonly affects lists with gdk:texture objects stored.

Performance Considerations
Internally, the gtk:list-store object was implemented with a linked list with a tail pointer prior to GTK 2.6. As a result, it was fast at data insertion and deletion, and not fast at random data access. The gtk:list-store object sets the :iters-persist flag of the gtk:tree-model-flags flags, which means that gtk:tree-iter iterators can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK, it is worth keeping the iterator around.

Atomic Operations
It is important to note that only the gtk:list-store-insert-with-values method is atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to the gtk:tree-model interface signaling. In contrast, using, for example, the gtk:list-store-append function and then the gtk:list-store-set function will first create a row, which triggers the "row-inserted" signal on the gtk:list-store object. The row, however, is still empty, and any signal handler connecting to the "row-inserted" signal on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the gtk:list-store object inside a gtk:tree-model-filter object and are using a gtk:tree-model-filter-visible-func callback function. Using any of the non-atomic operations to append rows to the gtk:list-store object will cause the gtk:tree-model-filter-visible-func callback function to be visited with an empty row first. The function must be prepared for that.
Examples:
Creating a simple list store.
(defun create-and-fill-model ()
  (let ((listdata '("Name1" "Name2" "Name3" "Name4" "Name5"))
        ;; Create new list store with three columns
        (store (make-instance 'gtk:list-store
                              :column-types
                              '("gint" "gchararray" "gboolean"))))
    ;; Fill in some data
    (iter (for data in listdata)
          (for i from 0)
          ;; Add a new row to the model
          (gtk:list-store-set store
                              (gtk:list-store-append store)
                              i
                              data
                              nil))
    ;; Modify particular row
    (let ((path (gtk:tree-path-new-from-string "2")))
      (gtk:list-store-set-value store
                                (gtk:tree-model-iter store path)
                                2
                                t))
    ;; Return new list store
    store))    
GtkListStore as GtkBuildable:
The gtk:list-store implementation of the gtk:buildable interface allows to specify the model columns with a <columns> element that may contain multiple <column> elements, each specifying one model column. The type attribute specifies the data type for the column.

Additionally, it is possible to specify content for the list store in the UI definition, with the <data> element. It can contain multiple <row> elements, each specifying to content for one row of the list model. Inside a <row>, the <col> elements specify the content for individual cells.

Note that it is probably more common to define your models in the code, and one might consider it a layering violation to specify the content of a list store in a UI definition, data, not presentation, and common wisdom is to separate the two, as far as possible.

Example: A UI Definition fragment for a list store
   <object class="GtkListStore">
     <columns>
       <column type="gchararray"/>
       <column type="gchararray"/>
       <column type="gint"/>
     </columns>
     <data>
       <row>
         <col id="0">John</col>
         <col id="1">Doe</col>
         <col id="2">25</col>
       </row>
       <row>
         <col id="0">Johan</col>
         <col id="1">Dahlin</col>
         <col id="2">50</col>
       </row>
     </data>
   </object>    
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-new (&rest column-types)
Arguments:
column-types -- g:type-t type IDs for the columns, from first to last
Returns:
The new gtk:list-store object.
Details:
Creates a new list store as with each of the types passed in. Note that only types derived from standard g:type-t fundamental type IDs are supported.
Examples:
The following example creates a new gtk:list-store object with three columnes, of type "gint", "gchararray" and "GdkPixbuf".
(gtk:list-store-new "gint" "gchararray" "GdkPixbuf")    
Note that in the Lisp binding a second implementation is
(make-instance 'gtk:list-store
               :column-types '("gint" "gchararray" "GdkPixbuf"))    
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-set (model iter &rest values)
Arguments:
model -- a gtk:list-store object
iter -- a gtk:tree-iter row iterator
values -- values to set
Returns:
The gtk:tree-iter iterator for the row being modified.
Details:
Sets the values of one or more cells in the row referenced by iter. The variable argument list should contain the values to be set.
Examples:
(let ((model (gtk:list-store-new "gchararray" "gchararray" "guint")))
  ;; Append a row and fill in some data
  (gtk:list-store-set model
                      (gtk:list-store-append model)
                      "Hans" "Müller" 1961)
   ... )    
Notes:
The Lisp implementation does not support pairs of a column index and a value, but a list of values. Therefore, it is not possible to set the values of individual columns. See the gtk:list-store-set-value function for setting the value of single columns.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-set-value (model iter column value)
Arguments:
model -- a gtk:list-store object
iter -- a valid gtk:tree-iter iterator for the row being modified
column -- an integer with the column number to modify
value -- a new value for the cell
Details:
Sets the data in the cell specified by iter and column. The type of value must be convertible to the type of column.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-remove (model iter)
Arguments:
model -- a gtk:list-store object
iter -- a valid gtk:tree-iter iterator
Returns:
True if iter is valid, nil if not.
Details:
Removes the given row from the list store. After being removed, iter is set to be the next valid row, or invalidated if it pointed to the last row in the list store.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-insert (model pos)
Arguments:
model -- a gtk:list-store object
pos -- an integer with the position to insert the new row
Returns:
The gtk:tree-iter iterator of the new row.
Details:
Creates a new row at pos. The returned iterator will point to this new row. If the pos argument is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty after this function is called. To fill in values, you need to call the gtk:list-store-set or gtk:list-store-set-value functions.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-insert-before (model sibling)
Arguments:
model -- a gtk:list-store object
sibling -- a valid gtk:tree-iter iterator, or nil
Returns:
The gtk:tree-iter iterator to the new row.
Details:
Inserts a new row before sibling. If sibling is nil, then the row will be appended to the end of the list. The returned iterator will point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:list-store-set or gtk:list-store-set-value functions.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-insert-after (model sibling)
Arguments:
model -- a gtk:list-store object
sibling -- a valid gtk:tree-iter, or nil
Returns:
The gtk:tree-iter iterator to the new row.
Details:
Inserts a new row after sibling. If sibling is nil, then the row will be prepended to the beginning of the list. The returned iterator will point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:list-store-set or gtk:list-store-set-value functions.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-insert-with-values (model pos &rest values)
Arguments:
model -- a gtk:list-store object
pos -- an integer with the position to insert the new row, or -1 to append after existing rows
values -- values to store in model
Returns:
The gtk:tree-iter iterator to the new row.
Details:
Creates a new row at pos. The returned iterator will point to this new row. If pos is -1, or larger than the number of rows in the list, then the new row will be appended to the list. The row will be filled with the values given to this function.

Calling the gtk:list-store-insert-with-values function has the same effect as calling
 (let ((iter (gtk:list-store-insert model pos)))
   (gtk:list-store-set model iter  ...)
 )  
with the difference that the former will only emit a "row-inserted" signal, while the latter will emit "row-inserted", "row-changed" and, if the list store is sorted, "rows-reordered" signals. Since emitting the "rows-reordered" signal repeatedly can affect the performance of the program, the gtk:list-store-insert-with-values function should generally be preferred when inserting rows in a sorted list store.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-prepend (model)
Arguments:
model -- a gtk:list-store object
Returns:
The gtk:tree-iter iterator to the prepended row.
Details:
Prepends a new row to model. The returned iterator will point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:list-store-set or gtk:list-store-set-value functions.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-append (model)
Arguments:
model -- a gtk:list-store object
Returns:
The gtk:tree-iter iterator to the appended row.
Details:
Appends a new row to the list store. The returned iterator will point to the new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:list-store-set or gtk:list-store-set-value functions.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
2024-4-7
Function gtk:list-store-clear (model)
Arguments:
model -- a gtk:list-store object
Details:
Removes all rows from the list store.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-iter-is-valid (model iter)
Arguments:
model -- a gtk:list-store object
iter -- a gtk:tree-iter iterator
Returns:
True if iter is valid, nil if iter is invalid.
Details:
Checks if the given iter is a valid iterator for this gtk:list-store.
Warning:
This function is slow. Only use it for debugging and/or testing purposes.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-reorder (model order)
Arguments:
model -- a gtk:list-store object
order -- a list of integer mapping the new position of each row to its old position before the re-ordering
Details:
Reorders model to follow the order indicated by order. Note that this function only works with unsorted stores.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-swap (model a b)
Arguments:
model -- a gtk:list-store object
a -- a gtk:tree-iter iterator
b -- a gtk:tree-iter iterator
Details:
Swaps a and b in model. Note that this function only works with unsorted stores.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-move-before (model iter pos)
Arguments:
model -- a gtk:list-store object
iter -- a gtk:tree-iter iterator
pos -- a gtk:tree-iter iterator, or nil
Details:
Moves iter in model to the position before pos. Note that this function only works with unsorted stores. If the pos argument is nil, iter will be moved to the end of the list.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7
Function gtk:list-store-move-after (model iter pos)
Arguments:
model -- a gtk:list-store object
iter -- a gtk:tree-iter iterator
pos -- a gtk:tree-iter iterator or nil
Details:
Moves iter in model to the position after pos. Note that this function only works with unsorted stores. If the pos argument is nil, iter will be moved to the start of the list.
Warning:
The gtk:list-store implementation is deprecated since 4.10. Use the g:list-store object instead.
See also:
#2024-4-7

GtkTreeStore

Class gtk:tree-store
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:tree-store object is a list model for use with a gtk:tree-view widget. It implements the gtk:tree-model interface, and consequentialy, can use all of the methods available there. It also implements the gtk:tree-sortable interface so it can be sorted by the tree view. Finally, it also implements the tree drag and drop interfaces.
GtkTreeStore as GtkBuildable:
The gtk:tree-store implementation of the gtk:buildable interface allows to specify the model columns with a <columns> element that may contain multiple <column> elements, each specifying one model column. The "type" attribute specifies the data type for the column.

Example: A UI Definition fragment for a tree store
<object class="GtkTreeStore">
  <columns>
    <column type="gchararray"/>
    <column type="gchararray"/>
    <column type="gint"/>
  </columns>
</object>    
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
2024-5-16
Function gtk:tree-store-new (&rest types)
Arguments:
types -- all g:type-t type IDs for the columns, from first to last
Returns:
The new gtk:tree-store object.
Details:
Creates a new tree store as with columns of the types passed in. Note that only types derived from standard GType fundamental types are supported.
Examples:
The following example creates a new gtk:tree-store object with three columns, of type "gint", "gchararray", and "GdkPixbuf" respectively.
(gtk:tree-store-new "gint" "gchararray" "GdkPixbuf")    
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
2024-5-16
Function gtk:tree-store-set-column-types (store types)
Arguments:
store -- a gtk:tree-store object
types -- a list with the g:type-t type IDs, one for each column
Details:
This function is meant primarily for GObjects that inherit from the gtk:tree-store class, and should only be used when constructing a new gtk:tree-store object. It will not function after a row has been added, or a method on a gtk:tree-model object is called.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-set-value (store iter column value)
Arguments:
store -- a gtk:tree-store object
iter -- a valid gtk:tree-iter iterator for the row being modified
column -- an integer with the column number to modify
value -- a new value for the cell
Details:
Sets the data in the cell specified by iter and column. The type of value must be convertible to the type of the column.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-set (store iter &rest values)
Arguments:
store -- a gtk:tree-store object
iter -- a valid gtk:tree-iter iterator for the row being modified
values -- values to set
Returns:
The gtk:tree-iter iterator for the row being modified.
Details:
Sets the values of one or more cells in the row referenced by iter. The variable argument list should contain the values to be set.
Examples:
(let ((model (gtk:tree-store-new "gchararray" "gchararray" "guint")))
  ;; First Book
  (let ((iter (gtk:tree-store-append model nil))) ; Toplevel iterator
    ;; Set the toplevel row
    (gtk:tree-store-set model
                        iter
                        "The Art of Computer Programming"
                        "Donald E. Knuth"
                        2011)
    ;; Append and set three child rows
    (gtk:tree-store-set model
                        (gtk:tree-store-append model iter) ; Child iterator
                        "Volume 1: Fundamental Algorithms"
                        ""
                        1997)
  ... ))    
Notes:
The Lisp implementation does not support pairs of a column index and a value, but a list of values. Therefore, it is not possible to set individual columns. See the gtk:tree-store-set-value function for setting the value of single columns.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
2024-5-16
Function gtk:tree-store-remove (store iter)
Arguments:
store -- a gtk:tree-store object
iter -- a valid gtk:tree-iter iterator
Returns:
True if iter is still valid, nil if not.
Details:
Removes the given row from the tree store. After being removed, iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one in the tree store.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-insert (store parent position)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
position -- an integer with the position to insert the new row
Returns:
The gtk:tree-iter iterator to the new row.
Details:
Creates a new row at position. If parent is non-nil, then the row will be made a child of parent. Otherwise, the row will be created at the toplevel. If position is larger than the number of rows at that level, then the new row will be inserted to the end of the list. The returned iterator point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:tree-store-set or gtk:tree-store-set-value functions.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-insert-before (store parent sibling)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
sibling -- a valid gtk:tree-iter iterator, or nil
Details:
Inserts a new row before sibling. If sibling is nil, then the row will be appended to parent's children. If parent and sibling are nil, then the row will be appended to the toplevel. If both sibling and parent are set, then parent must be the parent of sibling. When sibling is set, parent is optional.

The returned iterator point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:tree-store-set or gtk:tree-store-set-value functions.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-insert-after (store parent sibling)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
sibling -- a valid gtk:tree-iter iterator, or nil
Details:
Inserts a new row after sibling. If sibling is nil, then the row will be prepended to parent's children. If parent and sibling are nil, then the row will be prepended to the toplevel. If both sibling and parent are set, then parent must be the parent of sibling. When sibling is set, parent is optional.

The returned iterator point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:tree-store-set or gtk:tree-store-set-value functions.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-insert-with-values (store parent position &rest values)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
position -- an integer with the position to insert the new row, or -1 to append after existing rows
values -- pairs of column number and value
Returns:
The gtk:tree-iter iterator.
Details:
Creates a new row at position. The returned iterator point to this new row. If position is -1, or larger than the number of rows on the list, then the new row will be appended to the list. The row will be filled with the values given to this function.

Calling this function has the same effect as calling
(let ((iter (gtk:tree-store-insert store iter position)))
  (gtk:tree-store-set store iter values)
  .. )  
with the different that the former will only emit a "row-inserted" signal, while the latter will emit "row-inserted", "row-changed" and if the tree store is sorted, "rows-reordered". Since emitting the "rows-reordered" signal repeatedly can affect the performance of the program, the gtk:tree-store-insert-with-values function should generally be preferred when inserting rows in a sorted tree store.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-prepend (store parent)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
Returns:
The gtk:tree-iter iterator.
Details:
Prepends a new row to store. If parent is non-nil, then it will prepend the new row before the first child of parent, otherwise it will prepend a row to the toplevel. The returned iterator point to this new row. The row will be empty after this function is called. To fill in values, you need to call the gtk:tree-store-set or gtk:tree-store-set-value functions.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-append (store parent)
Arguments:
store -- a gtk:tree-store object
parent -- a valid gtk:tree-iter iterator, or nil
Returns:
The gtk:tree-iter iterator of the appended row.
Details:
Appends a new row to the tree store. If parent is non-nil, then it will append the new row after the last child of parent, otherwise it will append a row to the toplevel. The row will be empty after this function is called. To fill in values, you need to call the gtk:tree-store-set or gtk:tree-store-set-value functions.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
2024-11-5
Function gtk:tree-store-is-ancestor (store iter descendant)
Arguments:
store -- a gtk:tree-store object
iter -- a valid gtk:tree-iter iterator
descendant -- a valid gtk:tree-iter iterator
Returns:
True, if iter is an ancestor of descendant.
Details:
Returns true if iter is an ancestor of descendant. That is, iter is the parent, or grandparent or great-grandparent, of descendant.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-iter-depth (store iter)
Arguments:
store -- a gtk:tree-store object
iter -- a valid gtk:tree-iter iterator
Returns:
The depth of iter.
Details:
Returns the depth of iter. This will be 0 for anything on the root level, 1 for anything down a level, etc.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-clear (store)
Arguments:
store -- a gtk:tree-store object
Details:
Removes all rows from the tree store.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-iter-is-valid (store iter)
Arguments:
store -- a gtk:tree-store object
iter -- a gtk:tree-iter iterator
Returns:
True if iter is valid, nil if iter is invalid.
Details:
Checks if the given iter is a valid iterator for this gtk:tree-store object.
Notes:
This function is slow. Only use it for debugging and/or testing purposes.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-reorder (store parent order)
Arguments:
store -- a gtk:list-store object
parent -- a gtk:tree-iter iterator
order -- a list of integer mapping the new position of each child row to its old position before the re-ordering
Details:
Reorders the children of parent in store to follow the order indicated by order. Note that this function only works with unsorted stores.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-swap (store a b)
Arguments:
store -- a gtk:tree-store object
a -- a gtk:tree-iter iterator
b -- another gtk:tree-iter iterator
Details:
Swaps a and b in the same level of store. Note that this function only works with unsorted stores.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-move-before (store iter position)
Arguments:
store -- a gtk:tree-store
iter -- a gtk:tree-iter iterator
position -- a gtk:tree-iter iterator or nil
Details:
Moves iter in store to the position before position. iter and position should be in the same level. Note that this function only works with unsorted stores. If position is nil, iter will be moved to the end of the level.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16
Function gtk:tree-store-move-after (store iter position)
Arguments:
store -- a gtk:tree-store object
iter -- a gtk:tree-iter iterator
position -- a gtk:tree-iter iterator
Details:
Moves iter in store to the position after position. iter and position should be in the same level. Note that this function only works with unsorted stores. If position is nil, iter will be moved to the start of the level.
Warning:
The gtk:tree-store implementation is deprecated since 4.10. Use the gtk:tree-list-model object instead.
See also:
#2024-5-16

GtkComboBox

Class gtk:combo-box
Superclasses:
Documented Subclasses:
Direct Slots:
active
The active property of type :int (Read / Write)
The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value (first (gtk:tree-path-indices path)), where path is the gtk:tree-path instance of the active item.
Allowed values: >= -1
Default value: -1
active-id
The active-id property of type :string (Read / Write)
The value of the ID column of the active row.
Default value: nil
button-sensitivity
The button-sensitivity property of type gtk:sensitivity-type (Read / Write)
Whether the dropdown button is sensitive when the model is empty.
Default value: :auto
child
The child property of type gtk:widget (Read / Write)
The child widget.
entry-text-column
The entry-text-column property of type :int (Read / Write)
The column in the model of the combo box to associate with strings from the entry if the combo box was created with the value true for the has-entry property.
Allowed values: >= -1
Default value: -1
has-entry
The has-entry property of type :boolean (Read / Write / Construct)
Whether the combo box has an entry.
Default value: false
has-frame
The has-frame property of type :boolean (Read / Write)
Controls whether a frame is drawn around the text entry.
Default value: true
id-column
The id-column property of type :int (Read / Write)
The column in the combo box's model that provides string IDs for the values in the model, if not equal to -1.
Allowed values: >= -1
Default value: -1
model
The model property of type gtk:tree-model (Read / Write)
The model from which the combo box takes the values shown in the list.
popup-fixed-width
The popup-fixed-width property of type :boolean (Read / Write)
Whether the popup's width should be a fixed width matching the allocated width of the combo box.
Default value: true
popup-shown
The popup-shown property of type :boolean (Read)
Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to the "notify::popup-shown" signal.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:combo-box widget allows the user to choose from a list of valid choices. The gtk:combo-box widget displays the selected choice. When activated, the gtk:combo-box widget displays a popup which allows the user to make a new choice. The style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows style combo box.

The gtk:combo-box widget uses the model-view pattern. The list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since the gtk:combo-box class implements the gtk:cell-layout interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure.

To allow the user to enter values not in the model, the has-entry property allows the gtk:combo-box widget to contain a gtk:entry widget. This entry can be accessed by calling the gtk:combo-box-child function on the combo box.

For a simple list of textual choices, the model-view API of the gtk:combo-box widget can be a bit overwhelming. In this case, the gtk:combo-box-text widget offers a simple alternative. Both the gtk:combo-box widget and the gtk:combo-box-text widget can contain an entry.
CSS nodes:
 CSS nodes
 combobox
 ├── box.linked
 │   ╰── button.combo
 │       ╰── box
 │           ├── cellview
 │           ╰── arrow
 ╰── window.popup    
A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow.
 combobox
 ├── box.linked
 │   ├── entry.combo
 │   ╰── button.combo
 │       ╰── box
 │           ╰── arrow
 ╰── window.popup    
A gtk:combo-box widget with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow.
Accessibility:
The gtk:combo-box implementation uses the :combo-box role of the gtk:accessible-role enumeration.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
Signal Details:
The "activate" signal
lambda (combo)    :action      
combo
The gtk:combo-box widget that received the signal.
Emitted to when the combo box is activated. The signal is an action signal and emitting it causes the combo box to pop up its dropdown. Since 4.6
The "changed" signal
lambda (combo)    :run-last      
combo
The gtk:combo-box widget that received the signal.
The signal is emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to the gtk:combo-box-active-iter function. It will also be emitted while typing into the text entry of a combo box with an entry.
The "format-entry-text" signal
lambda (combo pathstr)    :run-last      
combo
The gtk:combo-box widget that received the signal.
pathstr
The string representing the gtk:tree-path instance from the combo box's current model to format text for.
Returns
The string representing the value at pathstr for the current gtk:combo-box model.
A signal which allows you to change how the text displayed in a entry of the combo box is displayed. Connect a signal handler which returns an allocated string representing path. That string will then be used to set the text in the text entry of the combo box. The default signal handler uses the text from the entry-text-column property model column. Here is an example signal handler which fetches data from the model and displays it in the text entry. For combo boxes that are created with a text entry. See the has-entry property.
(defun format-entry-text-callback (combo pathstr)
  (let* ((model (gtk:combo-box-model combo))
         (iter (gtk:tree-model-iter-from-string model pathstr))
         (value (gtk:tree-model-value model iter col-value)))
    (format nil "~a" value)))      
The "move-active" signal
lambda (combo scroll)    :action      
combo
The gtk:combo-box widget that received the signal.
scroll
The value of the gtk:scroll-type enumeration.
A keybinding signal which gets emitted to move the active selection.
The "popdown" signal
lambda (combo)    :action      
combo
The gtk:combo-box widget that received the signal.
A keybinding signal which gets emitted to popdown the combo box list. The default bindings for this signal are the Alt+Up and Escape keys.
The "popup" signal
lambda (combo)    :action      
combo
The gtk:combo-box widget that received the signal.
A keybinding signal which gets emitted to popup the combo box list. The default binding for this signal is the Alt+Down key.
See also:
2024-4-7
Accessor gtk:combo-box-active (object)
Syntax:
(gtk:combo-box-active object) => index
(setf (gtk:combo-box-active object) index)
Arguments:
object -- a gtk:combo-box widget
index -- an integer with the index in the model passed during construction, or -1 to have no active item
Details:
Accessor of the active slot of the gtk:combo-box class. The gtk:combo-box-active function returns the index of the currently active item, or -1 if there is no active item. The (setf gtk:combo-box-active) function sets the active item.

If the model is a non-flat tree model, and the active item is not an immediate child of the root of the tree, this function returns (first (gtk:tree-path-indices path)), where path is the gtk:tree-path instance of the active item.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-active-id (object)
Syntax:
(gtk:combo-box-active-id object) => id
(setf (gtk:combo-box-active-id object) id)
Arguments:
object -- a gtk:combo-box widget
id -- a string with the ID of the row to select, or nil
Details:
Accessor of the active-id slot of the gtk:combo-box class. The gtk:combo-box-active-id function returns the ID of the active row of the combo box. This value is taken from the active row and the column specified by the id-column property of the combo box. The (setf gtk:combo-box-active-id) function changes the active row of the combo box to the one that has an ID equal to id, or unsets the active row if the id argument is nil. Rows having a nil ID string cannot be made active by this function.

If the id-column property of the combo box is unset or if no row has the given ID then the function does nothing and returns nil.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-button-sensitivity (object)
Syntax:
(gtk:combo-box-button-sensitivity object) => sensitivity
(setf (gtk:combo-box-button-sensitivity object) sensitivity)
Arguments:
object -- a gtk:combo-box widget
sensitivity -- a value of the gtk:sensitivity-type enumeration
Details:
Accessor of the button-sensitivity slot of the gtk:combo-box class. The gtk:combo-box-button-sensitivity function returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. The (setf gtk:combo-box-button-sensitivity) function sets the sensitivity.

The :on value if the dropdown button is sensitive when the model is empty, the :off value if the button is always insensitive or the :auto value if it is only sensitive as long as the model has one item to be selected.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-child (object)
Syntax:
(gtk:combo-box-child object) => child
(setf (gtk:combo-box-child object) child)
Arguments:
object -- a gtk:combo-box widget
child -- a gtk:widget child widget
Details:
Accessor of the child slot of the gtk:combo-box class. The gtk:combo-box-child function gets the child of the combo box. The (setf gtk:combo-box-child) function sets the child widget.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-entry-text-column (object)
Syntax:
(gtk:combo-box-entry-text-column object) => column
(setf (gtk:combo-box-entry-text-column object) column)
Arguments:
object -- a gtk:combo-box widget
column -- an integer with a column in the model to get the strings from for the internal entry
Details:
Accessor of the entry-text-column slot of the gtk:combo-box class. The gtk:combo-box-entry-text-column function returns the column which the combo box is using to get the strings from to display in the internal entry. The (setf gtk:combo-box-entry-text-column) function sets the model column which the combo box should use to get strings.

The column value in the model of the combo box must be of type gchararray. This is only relevant if the combo box has been created with the has-entry property as true.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-has-entry (object)
Syntax:
(gtk:combo-box-has-entry object) => setting
Arguments:
object -- a gtk:combo-box widget
setting -- a boolean whether the combo box has an entry
Details:
Accessor of the has-entry slot of the gtk:combo-box class. The gtk:combo-box-has-entry function returns whether the combo box has an entry.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-has-frame (object)
Syntax:
(gtk:combo-box-has-frame object) => setting
(setf (gtk:combo-box-has-frame object) setting)
Arguments:
object -- a gtk:combo-box widget
setting -- a boolean whether a frame is drawn around the text entry
Details:
Accessor of the has-frame slot of the gtk:combo-box class. Controls whether a frame is drawn around the text entry.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-id-column (object)
Syntax:
(gtk:combo-box-id-column object) => column
(setf (gtk:combo-box-id-column object) column)
Arguments:
object -- a gtk:combo-box widget
column -- an integer with a column in the model to get string IDs for values from
Details:
Accessor of the id-column slot of the gtk:combo-box class. The gtk:combo-box-id-column function returns the model column which the combo box is using to get string IDs for values from. The (setf gtk:combo-box-id-column) function sets the model column.

The column value in the model of the combo box must be of type gchararray.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-model (object)
Syntax:
(gtk:combo-box-model object) => model
(setf (gtk:combo-box-model object) model)
Arguments:
object -- a gtk:combo-box widget
model -- a gtk:tree-model object
Details:
Accessor of the model slot of the gtk:combo-box class. The gtk:combo-box-model function returns the model which is acting as data source for the combo box. The (setf gtk:combo-box-model) function sets the model. Will unset a previously set model, if applicable. If model is nil, then it will unset the model.

Note that this function does not clear the cell renderers, you have to call the gtk:cell-layout-clear function yourself if you need to set up different cell renderers for the new model.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-popup-fixed-width (object)
Syntax:
(gtk:combo-box-popup-fixed-width object) => fixed
(setf (gtk:combo-box-popup-fixed-width object) fixed)
Arguments:
object -- a gtk:combo-box widget
fixed -- a boolean whether to use a fixed popup width
Details:
Accessor of the popup-fixed-width slot of the gtk:combo-box class. The gtk:combo-box-popup-fixed-width function gets whether the popup uses a fixed width matching the allocated width of the combo box. The (setf gtk:combo-box-popup-fixed-width) function specifies whether the width of the popup should be a fixed.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Accessor gtk:combo-box-popup-shown (object)
Syntax:
(gtk:combo-box-popup-shown object) => setting
(setf (gtk:combo-box-popup-shown object) setting)
Arguments:
object -- a gtk:combo-box widget
setting -- a boolean whether the combo boxes dropdown is popped up
Details:
Accessor of the popup-shown slot of the gtk:combo-box class. Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to the "notify::popup-shown" signal.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-26
Function gtk:combo-box-new ()
Returns:
The new gtk:combo-box widget.
Details:
Creates a new empty combo box.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7
Function gtk:combo-box-new-with-entry ()
Returns:
The new gtk:combo-box widget.
Details:
Creates a new empty combo box with an entry.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7
Function gtk:combo-box-new-with-model (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The new gtk:combo-box widget.
Details:
Creates a new combo box with the model initialized to model.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7
Function gtk:combo-box-new-with-model-and-entry (model)
Arguments:
model -- a gtk:tree-model object
Returns:
The new gtk:combo-box widget.
Details:
Creates a new empty combo box with an entry and with the model initialized to model.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7
Function gtk:combo-box-active-iter (combo)
Syntax:
(gtk:combo-box-active-iter combo) => iter
(setf (gtk:combo-box-active-iter combo) iter)
Arguments:
combo -- a gtk:combo-box widget
iter -- a gtk:tree-iter instance, or nil
Details:
Accessor of the active iterator of the combo box. The gtk:combo-box-active-iter function returns iter to point to the current active item, if it exists. The (setf gtk:combo-box-active-iter) function sets the current active item to be the one referenced by iter, or unsets the active item if iter is nil.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-26
Function gtk:combo-box-popup (combo)
Arguments:
combo -- a gtk:combo-box widget
Details:
Pops up the menu or dropdown list of the combo box. This function is mostly intended for use by accessibility technologies. Applications should have little use for it.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-7
Function gtk:combo-box-popup-for-device (combo device)
Arguments:
combo -- a gtk:combo-box widget
device -- a gdk:device object
Details:
Pops up the menu or dropdown list of the combo box. The popup window will be grabbed so only device and its associated pointer/keyboard are the only gdk:device objects able to send events to it.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-7
Function gtk:combo-box-popdown (combo)
Arguments:
combo -- a gtk:combo-box widget
Details:
Hides the menu or dropdown list of the combo box. This function is mostly intended for use by accessibility technologies. Applications should have little use for it.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-7
Function gtk:combo-box-set-row-separator-func (combo func)
Arguments:
combo -- a gtk:combo-box widget
func -- a gtk:tree-view-row-separator-func callback function
Details:
Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is nil, no separators are drawn. This is the default value.
Warning:
The gtk:combo-box implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7

GtkComboBoxText

Class gtk:combo-box-text
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:combo-box-text widget is a simple variant of the gtk:combo-box widget that hides the model-view complexity for simple text-only use cases. To create a gtk:combo-box-text widget, use the gtk:combo-box-text-new or gtk:combo-box-text-new-with-entry functions.

You can add items to a gtk:combo-box-text widget with the gtk:combo-box-text-append-text, gtk:combo-box-text-insert-text or gtk:combo-box-text-prepend-text functions and remove options with the gtk:combo-box-text-remove function.

If the gtk:combo-box-text widget contains an entry via the has-entry property, its contents can be retrieved using the gtk:combo-box-text-active-text function. The entry itself can be accessed by calling the gtk:combo-box-child function on the combo box.

You should not call the gtk:combo-box-model function or attempt to pack more cells into this combo box via its gtk:cell-layout interface.
GtkComboBoxText as GtkBuildable:
The gtk:combo-box-text implementation of the gtk:buildable interface supports adding items directly using the <items> element and specifying <item> elements for each item. Each <item> element supports the regular translation attributes "translatable", "context" and "comments".

Example: A UI definition fragment specifying gtk:combo-box-text items
 <object class="GtkComboBoxText">
   <items>
     <item translatable="yes">Factory</item>
     <item translatable="yes">Home</item>
     <item translatable="yes">Subway</item>
   </items>
 </object>    
CSS nodes:
 combobox
 ╰── box.linked
     ├── entry.combo
     ├── button.combo
     ╰── window.popup    
The gtk:combo-box-text implementation has a single CSS node with name combobox. It adds the .combo style class to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget with a gtk:string-list object instead.
See also:
2024-4-6
Function gtk:combo-box-text-new ()
Returns:
The new gtk:combo-box-text widget.
Details:
Creates a new combo box text widget, which is a gtk:combo-box widget just displaying strings.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-6
Function gtk:combo-box-text-new-with-entry ()
Returns:
The new gtk:combo-box-text widget.
Details:
Creates a new combo box text widget, which is a gtk:combo-box widget just displaying strings. The combo box created by this function has an entry.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-6
Function gtk:combo-box-text-append (combo id text)
Arguments:
combo -- a gtk:combo-box-text widget
id -- a string ID for this value, or nil
text -- a string with the text
Details:
Appends text to the list of strings stored in the combo box. If the ID is non-nil then it is used as the ID of the row. This is the same as calling the gtk:combo-box-text-insert function with a position of -1.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-prepend (combo id text)
Arguments:
combo -- a gtk:combo-box widget
id -- a string ID for this value, or nil
text -- a string with the text
Details:
Prepends text to the list of strings stored in the combo box. If the ID is non-nil then it is used as the ID of the row. This is the same as calling the gtk:combo-box-text-insert function with a position of 0.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-insert (combo pos id text)
Arguments:
combo -- a gtk:combo-box-text widget
pos -- an integer with an index to insert text
id -- a string ID for this value, or nil
text -- a string with the text
Details:
Inserts text at the given position in the list of strings stored in the combo box. If the ID is non-nil then it is used as the ID of the row. See the id-column property. If the pos argument is negative then the text is appended.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-append-text (combo text)
Arguments:
combo -- a gtk:combo-box-text widget
text -- a string with the text
Details:
Appends text to the list of strings stored in the combo box. This is the same as calling the gtk:combo-box-text-insert-text function with a position of -1.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-6
Function gtk:combo-box-text-prepend-text (combo text)
Arguments:
combo -- a gtk:combo-box widget
text -- a string with the text
Details:
Prepends text to the list of strings stored in the combo box. This is the same as calling the gtk:combo-box-text-insert-text function with a position of 0.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-insert-text (combo pos text)
Arguments:
combo -- a gtk:combo-box-text widget
pos -- an integer with an index to insert text
text -- a string with the text
Details:
Inserts text at the given position in the list of strings stored in the combo box. If the pos argument is negative then the text is appended. This is the same as calling the gtk:combo-box-text-insert function with a nil ID string.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-remove (combo pos)
Arguments:
combo -- a gtk:combo-box widget
pos -- an integer with index of the item to remove
Details:
Removes the string at pos from the combo box.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-7
Function gtk:combo-box-text-remove-all (combo)
Arguments:
combo -- a gtk:combo-box-text widget
Details:
Removes all the text entries from the combo box.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
#2024-4-6
Function gtk:combo-box-text-active-text (combo)
Arguments:
combo -- a gtk:combo-box-text widget
Returns:
The string containing the currently active text.
Details:
Returns the currently active text in the combo box, or nil if none is selected. If the combo box contains an entry, this function will return its contents which will not necessarily be an item from the list.
Warning:
The gtk:combo-box-text implementation is deprecated since 4.10. Use the gtk:drop-down widget instead.
See also:
2024-4-6

GtkAppChooser

Interface gtk:app-chooser
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
content-type
The content-type property of type :string (Read / Write / Construct)
The content type of the application chooser.
Default value: nil
Slot Access Functions:
Details:
The gtk:app-chooser interface is an interface that can be implemented by widgets which allow the user to choose an application, typically for the purpose of opening a file. The main objects that implement this interface are the gtk:app-chooser-widget, gtk:app-chooser-dialog and gtk:app-chooser-button widgets.

Applications are represented by GIO g:app-info objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The gtk:app-chooser-widget widget provides detailed control over whether the shown list of applications should include default, recommended or fallback applications.

To obtain the application that has been selected in a gtk:app-chooser widget, use the gtk:app-chooser-app-info function.
Warning:
The gtk:app-chooser implementation is deprecated since 4.10. The application selection widgets should be implemented according to the design of each platform and/or application requiring them.
See also:
2024-4-26
Accessor gtk:app-chooser-content-type (object)
Syntax:
(gtk:app-chooser-content-type object) => content-type
Arguments:
object -- a gtk:app-chooser object
content-type -- a string with the content type
Details:
Accessor of the content-type slot of the gtk:app-chooser interface. The gtk:app-chooser-content-type function returns the current value of the content type.
Warning:
The gtk:app-chooser implementation is deprecated since 4.10.
See also:
2024-4-26
Function gtk:app-chooser-app-info (object)
Arguments:
object -- a gtk:app-chooser object
Returns:
The g:app-info object for the currently selected application, or nil if none is selected.
Details:
Returns the currently selected application.
Warning:
The gtk:app-chooser implementation is deprecated since 4.10.
See also:
2024-2-22
Function gtk:app-chooser-refresh (object)
Arguments:
object -- a gtk:app-chooser object
Details:
Reloads the list of applications.
Warning:
The gtk:app-chooser implementation is deprecated since 4.10.
See also:
2024-2-22

GtkAppChooserWidget

Class gtk:app-chooser-widget
Superclasses:
Documented Subclasses:
None
Direct Slots:
default-text
The default-text property of type :string (Read / Write)
Determines the text that appears in the widget when there are no applications for the given content type.
Default value: nil
show-all
The show-all property of type :boolean (Read / Write / Construct)
If true, the application chooser presents all applications in a single list, without subsections for default, recommended or related applications.
Default value: false
show-default
The show-default property of type :boolean (Read / Write / Construct)
Determines whether the application chooser should show the default handler for the content type in a separate section. If false, the default handler is listed among the recommended applications.
Default value: false
show-fallback
The show-fallback property of type :boolean (Read / Write / Construct)
Determines whether the application chooser should show a section for fallback applications. If false, the fallback applications are listed among the other applications.
Default value: false
show-other
The show-other property of type :boolean (Read / Write / Construct)
Determines whether the application chooser should show a section for other applications.
Default value: false
show-recommended
The show-recommended property of type :boolean (Read / Write / Construct)
Determines whether the application chooser should show a section for recommended applications. If false, the recommended applications are listed among the other applications.
Default value: true
Returned by:
Slot Access Functions:
Details:
The gtk:app-chooser-widget widget is a widget for selecting applications. It is the main building block for the gtk:app-chooser-dialog widget. Most applications only need to use the latter. But you can use this widget as part of a larger widget if you have special needs.

The gtk:app-chooser-widget widget offers detailed control over what applications are shown, using the show-default, show-recommended, show-fallback, show-other and show-all properties. See the gtk:app-chooser documentation for more information about these groups of applications.

To keep track of the selected application, use the "application-selected" and "application-activated" signals.
CSS nodes:
The gtk:app-chooser-widget implementation has a single CSS node with name appchooser.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10. The application selection widgets should be implemented according to the design of each platform and/or application requiring them.
Signal Details:
The "application-activated" signal
lambda (widget application)    :run-first      
widget
The gtk:app-chooser-widget widget which received the signal.
application
The activated g:app-info object.
Emitted when an application item is activated from the list of the widget. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the Space, Shift+Space, Return or Enter keys.
The "application-selected" signal
lambda (widget application)    :run-first      
widget
The gtk:app-chooser-widget widget which received the signal.
application
The selected g:app-info object.
Emitted when an application item is selected from the widget's list.
See also:
2024-2-22
Accessor gtk:app-chooser-widget-default-text (object)
Syntax:
(gtk:app-chooser-widget-default-text object) => text
(setf (gtk:app-chooser-widget-default-text object) text)
Arguments:
object -- a gtk:app-chooser-widget widget
text -- a string with the text that appears in the widget
Details:
Accessor of the default-text slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-default-text function returns the text that is shown if there are not applications that can handle the content type. The (setf gtk:app-chooser-widget-default-text) function sets the text that is shown if there are not applications that can handle the content type.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-widget-show-all (object)
Syntax:
(gtk:app-chooser-widget-show-all object) => setting
(setf (gtk:app-chooser-widget-show-all object) setting)
Arguments:
object -- a gtk:app-chooser-widget widget
setting -- a boolean whether the application chooser presents all applications in a single list
Details:
Accessor of the show-all slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-show-all function sets whether the application chooser should show all applications in a flat list. The (setf gtk:app-chooser-widget-show-all) function sets whether the application chooser should show all applications in a flat list.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-widget-show-default (object)
Syntax:
(gtk:app-chooser-widget-show-default object) => setting
(setf (gtk:app-chooser-widget-show-default object) setting)
Arguments:
object -- a gtk:app-chooser-widget widget
setting -- a boolean whether the application chooser should show the default handler
Details:
Accessor of the show-default slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-show-default function returns whether the application chooser should the default handler for the content type in a separate section. The (setf gtk:app-chooser-widget-show-default) function sets whether the application chooser should show the default handler.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-widget-show-fallback (object)
Syntax:
(gtk:app-chooser-widget-show-fallback object) => setting
(setf (gtk:app-chooser-widget-show-fallback object) setting)
Arguments:
object -- a gtk:app-chooser-widget widget
setting -- a boolean whether the application chooser should show a section for fallback applications
Details:
Accessor of the show-fallback slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-show-fallback function returns whether the application chooser should show a section for fallback applications. The (setf gtk:app-chooser-widget-show-fallback) function sets whether the application chooser should show related applications for the content type in a separate section.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-widget-show-other (object)
Syntax:
(gtk:app-chooser-widget-show-other object) => setting
(setf (gtk:app-chooser-widget-show-other object) setting)
Arguments:
object -- a gtk:app-chooser-widget widget
setting -- a boolean whether the application chooser should show a section for other applications
Details:
Accessor of the show-other slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-show-other function returns whether the application chooser should show a section for other applications. The (setf gtk:app-chooser-widget-show-other) function sets whether the application chooser should show applications which are unrelated to the content type.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Syntax:
(gtk:app-chooser-widget-show-recommended object) => setting
(setf (gtk:app-chooser-widget-show-recommended object) setting)
Arguments:
object -- a gtk:app-chooser-widget widget
setting -- a boolean whether the application chooser shuld show a section for recommended applications
Details:
Accessor of the show-recommended slot of the gtk:app-chooser-widget class. The gtk:app-chooser-widget-show-recommended function returns whether the application chooser should recommended applications. The (setf gtk:app-chooser-widget-show-recommended) function sets whether the application chooser should show recommended applications for the content type in a separate section.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-4-26
Function gtk:app-chooser-widget-new (content-type)
Arguments:
content-type -- a string with the content type to show applications for
Returns:
The newly created gtk:app-chooser-widget widget.
Details:
Creates a new application chooser widget for applications that can handle content of the given type.
Warning:
The gtk:app-chooser-widget implementation is deprecated since 4.10.
See also:
2024-2-22

GtkAppChooserDialog

Class gtk:app-chooser-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
gfile
The gfile property of type g:file (Read / Write / Construct Only)
The g:file object used by the gtk:app-chooser-dialog widget. The dialog's content type will be guessed from the file, if present.
heading
The heading property of type :string (Read / Write)
The text to show at the top of the dialog. The string may contain Pango markup.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:app-chooser-dialog widget shows a gtk:app-chooser-widget widget inside a gtk:dialog widget.

Note that the gtk:app-chooser-dialog widget does not have any interesting methods of its own. Instead, you should get the embedded gtk:app-chooser-widget class using the gtk:app-chooser-dialog-widget function and call its methods if the gtk:app-chooser interface is not sufficient for your needs.

To set the heading that is shown above the gtk:app-chooser-widget widget, use the gtk:app-chooser-dialog-heading function.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10. The application selection widgets should be implemented according to the design of each platform and/or application requiring them.
See also:
2023-8-29
Accessor gtk:app-chooser-dialog-gfile (object)
Syntax:
(gtk:app-chooser-dialog-gfile object) => file
(setf (gtk:app-chooser-dialog-gfile object) file)
Arguments:
object -- a gtk:app-chooser-dialog widget
file -- a g:file object
Details:
Accessor of the gfile slot of the gtk:app-chooser-dialog class. The g:file object used by the gtk:app-chooser-dialog widget. The dialog's content type will be guessed from the file, if present.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-dialog-heading (object)
Syntax:
(gtk:app-chooser-dialog-heading object) => heading
(setf (gtk:app-chooser-dialog-heading object) heading)
Arguments:
object -- a gtk:app-chooser-dialog widget
heading -- a string containing Pango markup
Details:
Accessor of the heading slot of the gtk:app-chooser-dialog class. The gtk:app-chooser-dialog-heading function returns the text to display at the top of the dialog. The (setf gtk:app-chooser-dialog-heading) function sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10.
See also:
2024-4-26
Function gtk:app-chooser-dialog-new (parent flags file)
Arguments:
parent -- a gtk:window, or nil
flags -- a gtk:dialog-flags value with the flags for this dialog
file -- a g:file object
Returns:
The newly created gtk:app-chooser-dialog widget.
Details:
Creates a new application chooser dialog for the provided g:file object, to allow the user to select an application for it.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10.
See also:
#2024-2-22
Function gtk:app-chooser-dialog-new-for-content-type (parent flags content-type)
Arguments:
parent -- a gtk:window, or nil
flags -- a gtk:dialog-flags value with the flags for this dialog
content-type -- a content type string
Returns:
The newly created gtk:app-chooser-dialog widget.
Details:
Creates a new application chooser dialog for the provided content type, to allow the user to select an application for it.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10.
See also:
#2024-2-22
Function gtk:app-chooser-dialog-widget (widget)
Arguments:
dialog -- a gtk:app-chooser-dialog widget
Returns:
The gtk:app-chooser-widget widget of dialog.
Details:
Returns the application chooser widget of the dialog.
Warning:
The gtk:app-chooser-dialog implementation is deprecated since 4.10.
See also:
#2024-4-26

GtkAppChooserButton

Class gtk:app-chooser-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
heading
The heading property of :string (Read / Write)
The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup.
Default value: nil
modal
The modal property of :boolean (Read / Write / Construct)
Whether the dialog should be modal.
Default value: true
show-default-item
The show-default-item property of type :boolean (Read / Write / Construct)
Whether the dropdown menu should show the default application on top for the provided content type.
Default value: false
show-dialog-item
The show-dialog-item property of type :boolean (Read / Write / Construct)
Whether the dropdown menu should show an item that triggers a gtk:app-chooser-dialog widget when clicked.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:app-chooser-button widget is a widget that lets the user select an application. It implements the gtk:app-chooser interface.

Figure: GtkAppChooserButton

Initially, a gtk:app-chooser-button widget selects the first application in its list, which will either be the most-recently used application or, if the show-default-item property is true, the default application.

The list of applications shown in a gtk:app-chooser-button widget includes the recommended applications for the given content type. When the show-default-item property is set, the default application is also included. To let the user chooser other applications, you can set the show-dialog-item property, which allows to open a full gtk:app-chooser-dialog widget.

It is possible to add custom items to the list, using the gtk:app-chooser-button-append-custom-item function. These items cause the "custom-item-activated" signal to be emitted when they are selected.

To track changes in the selected application, use the "changed" signal.
CSS nodes:
The gtk:app-chooser-button implementation has a single CSS node with the name appchooserbutton.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10. The application selection widgets should be implemented according to the design of each platform and/or application requiring them.
Signal Details:
The "activate" signal
lambda (button)    :run-first      
button
The gtk:app-chooser-button widget which received the signal.
Emitted to when the button is activated. The signal is an action signal and emitting it causes the button to pop up its dialog.
The "changed" signal
lambda (button)    :run-last      
button
The gtk:app-chooser-button widget which received the signal.
Emitted when the active application on the gtk:app-chooser-button widget changes.
The "custom-item-activated" signal
lambda (button item)    :has-details      
button
The gtk:app-chooser-button widget which received the signal.
item
The string with the name of the activated item.
Emitted when a custom item, previously added with the gtk:app-chooser-button-append-custom-item function, is activated from the dropdown menu.
See also:
2024-5-21
Accessor gtk:app-chooser-button-heading (object)
Syntax:
(gtk:app-chooser-button-heading object) => heading
(setf (gtk:app-chooser-button-heading object) heading)
Arguments:
object -- a gtk:app-chooser-button widget
heading -- a string containing Pango markup
Details:
Accessor of the heading slot of the gtk:app-chooser-button class. The gtk:app-chooser-button-heading function returns the text to display at the top of the dialog. The (setf gtk:app-chooser-button-heading) function sets the text to display at the top of the dialog.

If the heading is not set, the dialog displays a default text.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-button-modal (object)
Syntax:
(gtk:app-chooser-button-modal object) => setting
(setf (gtk:app-chooser-button-modal object) setting)
Arguments:
object -- a gtk:app-chooser-button widget
setting -- a boolean whether the dialog is modal
Details:
Accessor of the modal slot of the gtk:app-chooser-button class. The gtk:app-chooser-button-modal function gets whether the dialog is modal. The (setf gtk:app-chooser-button-modal) function sets whether the dialog should be modal.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-button-show-default-item (object)
Syntax:
(gtk:app-chooser-button-show-default-item object) => setting
(setf (gtk:app-chooser-button-show-default-item object) setting)
Arguments:
object -- a gtk:app-chooser-button widget
setting -- a boolean whether the dropdown menu should show the default application
Details:
Accessor of the show-default-item slot of the gtk:app-chooser-button class. The gtk:app-chooser-button-show-default-item function returns whether the dropdown menu of the button should show the default application. The (setf gtk:app-chooser-button-show-default-item) function sets whether the dropdown menu of the button should show the default application for the given content type at top.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
2024-4-26
Accessor gtk:app-chooser-button-show-dialog-item (object)
Syntax:
(gtk:app-chooser-button-show-dialog-item object) => setting
(setf (gtk:app-chooser-button-show-dialog-item object) setting)
Arguments:
object -- a gtk:app-chooser-button widget
setting -- a boolean whether the dropdown menu shoult show a gtk:app-chooser-dialog widget
Details:
Accessor of the show-dialog-item slot of the gtk:app-chooser-button class. The gtk:app-chooser-button-show-dialog-item function returns whether the dropdown menu of the button should show an entry to trigger a gtk:app-chooser-dialog widget. The (setf gtk:app-chooser-button-show-dialog-item) function sets the property.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
2024-4-26
Function gtk:app-chooser-button-new (content-type)
Arguments:
content-type -- a string with the content type to show applications for
Returns:
The newly created gtk:app-chooser-button widget.
Details:
Creates a new application chooser button for applications that can handle content of the given type.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
2023-8-29
Function gtk:app-chooser-button-append-custom-item (widget name label icon)
Arguments:
widget -- a gtk:app-chooser-button widget
name -- a string with the name of the custom item
label -- a string with the label for the custom item
icon -- a g:icon instance with the icon for the custom item
Details:
Appends a custom item to the list of applications that is shown in the popup. The item name must be unique per-widget. Clients can use the provided name as a detail for the "custom-item-activated" signal, to add a callback for the activation of a particular custom item in the list. See also the gtk:app-chooser-button-append-separator function.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
#2024-2-22
Function gtk:app-chooser-button-append-separator (widget)
Arguments:
widget -- a gtk:app-chooser-button widget
Details:
Appends a separator to the list of applications that is shown in the popup.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
#2024-2-22
Function gtk:app-chooser-button-set-active-custom-item (widget name)
Arguments:
widget -- a gtk:app-chooser-button widget
name -- a string with the name of the custom item
Details:
Selects a custom item previously added with the gtk:app-chooser-button-append-custom-item function. Use the gtk:app-chooser-refresh function to bring the selection to its initial state.
Warning:
The gtk:app-chooser-button implementation is deprecated since 4.10.
See also:
#2024-2-22

GtkColorChooser

Interface gtk:color-chooser
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
rgba
The rgba property of type gdk:rgba (Read / Write)
The currently selected color, as a RGBA color. The property can be set to change the current selection programmatically.
use-alpha
The use-alpha property of type :boolean (Read / Write)
Whether colors may have alpha (translucency). When it is false, the RGBA color obtained via the rgba property will be forced to have the alpha value 1.0. Implementations are expected to show alpha by rendering the color over a non-uniform background (like a checkerboard pattern).
Default value: true
Slot Access Functions:
Details:
The gtk:color-chooser interface is an interface that is implemented by widgets for choosing colors. Depending on the situation, colors may be allowed to have alpha (translucency).

The main widgets that implement this interface are the gtk:color-button, gtk:color-chooser-widget, and gtk:color-chooser-dialog widgets.
Warning:
The gtk:color-chooser implementation is deprecated since 4.10. Use the gtk:color-dialog and gtk:color-dialog-button widgets instead.
Signal Details:
The "color-activated" signal
lambda (chooser color)    :run-first      
chooser
The gtk:color-chooser widget which received the signal.
color
The gdk:rgba color.
Emitted when a color is activated from the color chooser. This usually happens when the user clicks a color swatch, or a color is selected and the user presses one of the Space, Shift+Space, Return or Enter keys.
See also:
2024-5-21
Accessor gtk:color-chooser-rgba (object)
Syntax:
(gtk:color-chooser-rgba object) => color
(setf (gtk:color-chooser-rgba object) color)
Arguments:
object -- a gtk:color-chooser widget
color -- a gdk:rgba color
Details:
Accessor of the rgba slot of the gtk:color-chooser class. The gtk:color-chooser-rgba function gets the currently selected color. The (setf gtk:color-chooser-rgba) function sets the color.
Warning:
The gtk:color-chooser implementation is deprecated since 4.10. Use the gtk:color-dialog widget instead.
See also:
2024-5-21
Accessor gtk:color-chooser-use-alpha (object)
Syntax:
(gtk:color-chooser-use-alpha object) => use-alpha
(setf (gtk:color-chooser-use-alpha object) use-alpha)
Arguments:
object -- a gtk:color-chooser widget
use-alpha -- true if the color chooser should use alpha channel, false if not
Details:
Accessor of the use-alpha slot of the gtk:color-chooser class. The gtk:color-chooser-use-alpha function returns whether the color chooser shows the alpha channel. The (setf gtk:color-chooser-use-alpha) function sets the property.
Warning:
The gtk:color-chooser implementation is deprecated since 4.10. Use the gtk:color-dialog widget instead.
See also:
2024-5-21
Function gtk:color-chooser-add-palette (chooser orientation colors-per-line colors)
Arguments:
chooser -- a gtk:color-chooser widget
orientation -- a value of the gtk:orientation enumeration
colors-per-line -- an integer with the number of colors to show in each row/column
colors -- a list with the gdk:rgba colors of the palette, or nil
Details:
Adds a palette to the color chooser. If the orientation is :horizontal, the colors are grouped in rows, with colors-per-line colors in each row. If the orientation is :vertical, the colors are grouped in columns instead.

The default color palette of the color chooser widget has 34 colors, organized in columns of 5 colors. This includes some grays. The layout of the color chooser widget works best when the palettes have 9-10 columns.

Calling this function for the first time has the side effect of removing the default color and gray palettes from the color chooser. If colors is nil, removes all previously added palettes.
Warning:
The gtk:color-chooser implementation is deprecated since 4.10. Use the gtk:color-dialog widget instead.
See also:
2024-5-21
Function gtk:hsv-to-rgb (h s v)
Arguments:
h -- a number coerced to a float with the hue component
s -- a number coerced to a float with the saturation component
v -- a number coerced to a float with the value component
Returns:
r -- a float with the red component
g -- a float with the green component
b -- a float with the blue component
Details:
Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range, output values will be in the same range.
See also:
2024-5-21
Function gtk:rgb-to-hsv (r g b)
Arguments:
r -- a number coerced to a float with the red component
g -- a number coerced to a float with the green component
b -- a number coerced to a float with the blue component
Returns:
h -- a float with the hue component
s -- a float with the saturation component
v -- a float with the value component
Details:
Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range. Output values will be in the same range.
See also:
2024-5-21

GtkColorChooserWidget

Class gtk:color-chooser-widget
Superclasses:
Documented Subclasses:
None
Direct Slots:
show-editor
The show-editor property of type :boolean (Read / Write)
True when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:color-chooser-widget widget lets the user select a color. By default, the chooser presents a prefined palette of colors, plus a small number of settable custom colors. It is also possible to select a different color with the single-color editor. To enter the single-color editing mode, use the context menu of any color of the palette, or use the '+' button to add a new custom color.

The chooser automatically remembers the last selection, as well as custom colors. To change the initially selected color or to get the selected color use the gtk:color-chooser-rgba function.

The gtk:color-chooser-widget widget is used in the gtk:color-chooser-dialog widget to provide a dialog for selecting colors.
CSS nodes:
The gtk:color-chooser-widget class has a single CSS node with name colorchooser.
Examples:
This example shows a color chooser widget in a window. The selected color is print on the console.
(defun do-color-chooser-widget (&optional application)
  (let* ((color-chooser (make-instance 'gtk:color-chooser-widget
                                       :margin-top 12
                                       :margin-bottom 12
                                       :margin-start 12
                                       :margin-end 12))
         (window (make-instance 'gtk:window
                                 :application application
                                 :child color-chooser
                                 :title "Color Chooser Widget"
                                 :border-width 12
                                 :default-width 400)))
    (g:signal-connect color-chooser "color-activated"
        (lambda (chooser color)
          (declare (ignore chooser))
          (format t "Selected color is ~a~%" (gdk:rgba-to-string color))))
    (gtk:window-present window)))    
Warning:
The gtk:color-chooser-widget implementation is deprecated since 4.10.
See also:
2024-5-21
Accessor gtk:color-chooser-widget-show-editor (object)
Syntax:
(gtk:color-chooser-widget-show-editor object) => show-editor
(setf (gtk:color-chooser-widget-show-editor object) show-editor)
Arguments:
object -- a gtk:color-chooser-widget widget
show-editor -- a boolean whether to show the single-color editor
Details:
Accessor of the show-editor slot of the gtk:color-chooser-widget class. The show-editor property is true when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode.
Warning:
The gtk:color-chooser-widget implementation is deprecated since 4.10.
See also:
2024-2-22
Function gtk:color-chooser-widget-new ()
Returns:
The new gtk:color-chooser-widget widget.
Details:
Creates a new color chooser widget.
Warning:
The gtk:color-chooser-widget implementation is deprecated since 4.10.
See also:
2024-2-22

GtkColorChooserDialog

Class gtk:color-chooser-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
show-editor
The show-editor property of type :boolean (Read / Write)
True when the color chooser dialog is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:color-chooser-dialog widget is a dialog for choosing a color. It implements the gtk:color-chooser interface and does not provide much API of its own.

Figure: GtkColorChooserDialog

To create a gtk:color-chooser-dialog widget, use the gtk:color-chooser-dialog-new function. To get or change the initially selected color, use the gtk:color-chooser-rgba function.
Examples:
Clicking on the drawing area opens a color chooser dialog to select a background color for the drawing area. The default palettes are replaced for this color chooser dialog.
(let ((message "Click to change the background color.")
      (bg-color (gdk:rgba-parse "White"))
      ;; Color palette with 9 Red RGBA colors
      (palette1 (list (gdk:rgba-parse "IndianRed")
                      (gdk:rgba-parse "LightCoral")
                      (gdk:rgba-parse "Salmon")
                      (gdk:rgba-parse "DarkSalmon")
                      (gdk:rgba-parse "LightSalmon")
                      (gdk:rgba-parse "Crimson")
                      (gdk:rgba-parse "Red")
                      (gdk:rgba-parse "FireBrick")
                      (gdk:rgba-parse "DarkRed")))
      ;; Gray palette with 9 gray RGBA colors
      (palette2 (list (gdk:rgba-parse "Gainsboro")
                      (gdk:rgba-parse "LightGray")
                      (gdk:rgba-parse "Silver")
                      (gdk:rgba-parse "DarkGray")
                      (gdk:rgba-parse "Gray")
                      (gdk:rgba-parse "DimGray")
                      (gdk:rgba-parse "LightSlateGray")
                      (gdk:rgba-parse "SlateGray")
                      (gdk:rgba-parse "DarkSlateGray"))))

(defun do-color-chooser-dialog (&optional application) (let* ((area (make-instance 'gtk:drawing-area)) (window (make-instance 'gtk:window :title "Color Chooser Dialog" :application application :child area :default-width 400)) (gesture (make-instance 'gtk:gesture-click))) ;; Draw the background color and a hint on the drawing area (gtk:drawing-area-set-draw-func area (lambda (widget cr width height) (declare (ignore widget width height)) (let (;(cr (pointer cr)) (red (gdk:rgba-red bg-color)) (green (gdk:rgba-green bg-color)) (blue (gdk:rgba-blue bg-color))) ;; Paint the current color on the drawing area (cairo:set-source-rgb cr red green blue) (cairo:paint cr) ;; Print a hint on the drawing area (cairo:set-source-rgb cr (- 1 red) (- 1 green) (- 1 blue)) (cairo:select-font-face cr "Sans") (cairo:set-font-size cr 12) (cairo:move-to cr 12 24) (cairo:show-text cr message)))) ;; Add the controller to the drawing area (gtk:widget-add-controller area gesture) ;; Create and run a color chooser dialog to select a background color (g:signal-connect gesture "pressed" (lambda (gesture n x y) (declare (ignore gesture n x y)) (let ((dialog (make-instance 'gtk:color-chooser-dialog :transient-for window :use-alpha nil))) ;; Add a custom palette to the dialog (gtk:color-chooser-add-palette dialog :vertical 1 palette1) ;; Add a second coustom palette to the dialog (gtk:color-chooser-add-palette dialog :vertical 1 palette2) ;; Set the actual background color for the color chooser (setf (gtk:color-chooser-rgba dialog) bg-color) ;; Connect handler to the response signal of the dialog (g:signal-connect dialog "response" (lambda (dialog response) (when (= -5 response) ; the :ok value ;; Change the background color for the drawing area (format t "new color is ~a~%" (gtk:color-chooser-rgba dialog)) (setf bg-color (gtk:color-chooser-rgba dialog)) (gtk:widget-queue-draw area)) (gtk:window-destroy dialog))) (gtk:widget-show dialog)))) ;; Show the window (gtk:window-present window))))
Warning:
The gtk:color-chooser-dialog implementation is deprecated since 4.10. Use the gtk:color-dialog object instead.
See also:
2024-5-21
Accessor gtk:color-chooser-dialog-show-editor (object)
Syntax:
(gtk:color-chooser-dialog-show-editor object) => show-editor
(setf (gtk:color-chooser-dialog-show-editor object) show-editor)
Arguments:
object -- a gtk:color-chooser-dialog widget
show-editor -- a boolean whether to show the single-color editor
Details:
Accessor of the show-editor slot of the gtk:color-chooser-dialog class. True when the color chooser dialog is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode.
Warning:
The gtk:color-chooser-dialog implementation is deprecated since 4.10. Use the gtk:color-dialog object instead.
See also:
2024-5-21
Function gtk:color-chooser-dialog-new (title parent)
Arguments:
title -- a string with the title of the dialog, or nil
parent -- a gtk:window transient parent of the dialog, or nil
Returns:
The new gtk:color-chooser-dialog widget.
Details:
Creates a new color chooser dialog.
Warning:
The gtk:color-chooser-dialog implementation is deprecated since 4.10. Use the gtk:color-dialog object instead.
See also:
2024-5-21

GtkColorButton

Class gtk:color-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
modal
The modal property of type :boolean (Read / Write)
Whether the color chooser dialog is modal.
Default value: true
show-editor
The show-editor property of type :boolean (Read / Write)
Set the property to true to skip the palette in the color chooser dialog and go directly to the color editor. This property should be used in cases where the palette in the editor would be redundant, such as when the color button is already part of a palette.
Default value: false
title
The title property of type :string (Read / Write)
The title of the color chooser dialog.
Default value: "Pick a Color"
Returned by:
Slot Access Functions:
Details:
The gtk:color-button widget is a button which displays the currently selected color and allows to open a color chooser dialog to change the color. It is a suitable widget for selecting a color in a preference dialog.

Figure: GtkColorButton
CSS nodes:
colorbutton
╰── button.color
    ╰── [content]    
The gtk:color-button implementation has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain gtk:button widget, it gets the .color style class.
Examples:
The example shows a color button. The button is initialized with the color "Blue". The handler for the "color-set" signal prints the selected color on the console.
(defun do-color-button (&optional application)
  (let* ((button (make-instance 'gtk:color-button
                                 :rgba (gdk:rgba-parse "Blue")
                                 :title "Choose a color from the palette"
                                 :margin-top 48
                                 :margin-bottom 48
                                 :margin-start 48
                                 :margin-end 48))
         (window (make-instance 'gtk:window
                                 :title "Color Button"
                                 :application application
                                 :child button
                                 :default-width 270
                                 :default-height 210)))
    (g:signal-connect button "color-set"
        (lambda (widget)
          (let ((rgba (gtk:color-chooser-rgba widget)))
            (format t "Selected color is ~a~%" (gdk:rgba-to-string rgba)))))
    (gtk:window-present window)))    
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
Signal Details:
The "activate" signal
lambda (button)    :run-first      
button
The gtk:color-button widget which received the signal.
The signal on the gtk:color-button widget is an action signal and emitting it causes the button to pop up its color chooser dialog. Since 4.4
The "color-set" signal
lambda (button)    :run-first      
button
The gtk:color-button widget which received the signal.
The signal is emitted when the user selects a color. When handling this signal, use the gtk:color-chooser-rgba function to find out which color was just selected. Note that this signal is only emitted when the user changes the color. If you need to react to programmatic color changes as well, use the "notify::color" signal.
See also:
2024-5-21
Accessor gtk:color-button-modal (object)
Syntax:
(gtk:color-button-modal object) => modal
(setf (gtk:color-button-modal object) modal)
Arguments:
object -- a gtk:color-button widget
modal -- a boolean whether the color chooser dialog is modal
Details:
Accessor of the modal slot of the gtk:color-button class. The gtk:color-button-modal function sets whether the color chooser dialog is modal. The (setf gtk:color-button-modal) function sets the property.
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
See also:
2024-5-21
Accessor gtk:color-button-show-editor (object)
Syntax:
(gtk:color-button-show-editor object) => show-editor
(setf (gtk:color-button-show-editor object) show-editor)
Arguments:
object -- a gtk:color-button widget
show-editor -- a boolean whether to skip the palette in the color chooser dialog
Details:
Accessor of the show-editor slot of the gtk:color-button class. Set this property to true to skip the palette in the color chooser dialog and go directly to the color editor. This property should be used in cases where the palette in the editor would be redundant, such as when the color button is already part of a palette.
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
See also:
2024-5-21
Accessor gtk:color-button-title (object)
Syntax:
(gtk:color-button-title object) => title
(setf (gtk:color-button-title object) title)
Arguments:
object -- a gtk:color-button widget
title -- a string containing the title of the color chooser dialog
Details:
Accessor of the title slot of the gtk:color-button class. The gtk:color-button-title function gets the title of the color chooser dialog. The (setf gtk:color-button-title) function sets the title.
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
See also:
2024-5-21
Function gtk:color-button-new ()
Returns:
The new gtk:color-button widget.
Details:
Creates a new color button. This returns a widget in the form of a button containing a swatch representing the currently selected color. When the button is clicked, a color chooser dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes.
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
See also:
2024-5-21
Function gtk:color-button-new-with-rgba (rgba)
Arguments:
rgba -- a gdk:rgba color to set the current color with
Returns:
The new gtk:color-button widget.
Details:
Creates a new color button with the given RGBA color. This returns a widget in the form of a button containing a swatch representing the currently selected color. When the button is clicked, a color chooser dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes.
Warning:
The gtk:color-button implementation is deprecated since 4.10. Use the gtk:color-dialog-button widget instead.
See also:
2024-5-21

GtkFileChooser

GEnum gtk:file-chooser-action
Declaration:
(gobject:define-genum "GtkFileChooserAction" gtk:file-chooser-action
  (:export t
   :type-initializer "gtk_file_chooser_action_get_type")
  (:open 0)
  (:save 1)
  (:select-folder 2))  
Values:
:open
Indicates Open mode. The file chooser will only let the user pick an existing file.
:save
Indicates Save mode. The file chooser will let the user pick an existing file, or type in a new filename.
:select-folder
Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder.
Details:
Describes whether a gtk:file-chooser widget is being used to open existing files or to save to a possibly new file.
See also:
2024-4-26
Interface gtk:file-chooser
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
action
The action property of type gtk:file-chooser-action (Read / Write)
The type of operation that the file selector is performing.
Default value: :open
create-folders
The create-folders property of type :boolean (Read / Write)
Whether a file chooser not in :open mode will offer the user to create new folders.
Default value: true
filter
The filter property of type gtk:file-filter (Read / Write)
The current filter for selecting which files are displayed.
filters
The filters property of type g:list-model (Read)
The list model containing the filters that have been added with the gtk:file-chooser-add-filter function.
select-multiple
The select-multiple property of type :boolean (Read / Write)
Whether to allow multiple files to be selected.
Default value: false
shortcut-folders
The shortcut-folders property of type g:list-model (Read)
The list model containing the shortcut folders that have been added with the gtk:file-chooser-add-shortcut-folder function.
Slot Access Functions:
Details:
The gtk:file-chooser interface is an interface that can be implemented by file selection widgets. The main widgets that implement this interface are the gtk:file-chooser-widget and gtk:file-chooser-dialog widgets. You do not need to write a widget that implements the gtk:file-chooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

The gtk:file-chooser interface allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:
Bookmarks
are created by the user, by dragging folders from the right pane to the left pane, or by using the "Add". Bookmarks can be renamed and deleted by the user.
Shortcuts
can be provided by the application or by the underlying filesystem abstraction, for example, both the gnome-vfs and the Windows filesystems provide "Desktop" shortcuts. Shortcuts cannot be modified by the user.
Volumes
are provided by the underlying filesystem abstraction. Volumes are the "roots" of the filesystem.
File Names and Encodings
When the user is finished selecting files in a gtk:file-chooser widget, the program can get the selected filenames as g:file objects.
Examples:
Sample usage with a gtk:file-chooser-dialog widget.
(defun create-file-chooser-dialog (parent)
  (let ((filter-all (gtk:file-filter-new))
        (filter-picture (gtk:file-filter-new))
        (dialog (gtk:file-chooser-dialog-new "File Chooser Dialog"
                                             parent
                                             :open
                                             "Open" 100
                                             "Cancel" :cancel)))
    (setf (gtk:window-modal dialog) t)
    (g:signal-connect dialog "response"
                      (lambda (dialog response)
                        (format t "  Response is ~a~%" response)
                        (unless (eq :cancel
                                    (gtk:response-type-keyword response))
                          (format t "Selected file is ~a~%"
                                  (gtk:file-chooser-namestring dialog)))
                        (gtk:window-destroy dialog)))
    ;; Add a file filter
    (setf (gtk:file-filter-name filter-all) "All Files")
    (gtk:file-filter-add-pattern filter-all "*")
    (gtk:file-chooser-add-filter dialog filter-all)
    ;; Add a second file filter for pictures
    (setf (gtk:file-filter-name filter-picture) "All Pictures")
    (gtk:file-filter-add-pixbuf-formats filter-picture)
    (gtk:file-chooser-add-filter dialog filter-picture)
    ;; Present the dialog
    (gtk:window-present dialog)))    
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-5-20
Accessor gtk:file-chooser-action (object)
Syntax:
(gtk:file-chooser-action object) => action
(setf (gtk:file-chooser-action object) action)
Arguments:
object -- a gtk:file-chooser widget
action -- a gtk:file-chooser-action value
Details:
Accessor of the action slot of the gtk:file-chooser interface. The gtk:file-chooser-action function gets the type of operation that the file chooser is performing. The (setf gtk:file-chooser-action) function sets the type of operation. The user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is :save but not if the action is :open.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26
Accessor gtk:file-chooser-create-folders (object)
Syntax:
(gtk:file-chooser-create-folders object) => setting
(setf (gtk:file-chooser-create-folders object) setting)
Arguments:
object -- a gtk:file-chooser widget
setting -- true if the New Folder button should be displayed
Details:
Accessor of the create-folders slot of the gtk:file-chooser interface. The gtk:file-chooser-create-folders function gets whether the file chooser will offer to create new folders. The (setf gtk:file-chooser-create-folders) function sets whether the file chooser will offer to create new folders. This is only relevant if the action of the file chooser is not set to be in :open mode.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26
Accessor gtk:file-chooser-filter (object)
Syntax:
(gtk:file-chooser-filter object) => filter
(setf (gtk:file-chooser-filter object) filter)
Arguments:
object -- a gtk:file-chooser widget
filter -- a gtk:file-filter object
Details:
Accessor of the filter slot of the gtk:file-chooser interface. The gtk:file-chooser-filter function gets the current filter. The (setf gtk:file-chooser-filter) function sets the current filter. Only the files that pass the filter will be displayed.

If the user selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26
Accessor gtk:file-chooser-filters (object)
Syntax:
(gtk:file-chooser-filters object) => filters
Arguments:
object -- a gtk:file-chooser widget
filters -- a g:list-model object containing the current set of user-selectable filters
Details:
Accessor of the filters slot of the gtk:file-chooser interface. The gtk:file-chooser-filters function gets the current set of user-selectable filters, as a list model. See the gtk:file-chooser-add-filter, and gtk:file-chooser-remove-filter functions.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-5-20
Accessor gtk:file-chooser-select-multiple (object)
Syntax:
(gtk:file-chooser-select-multiple object) => setting
(setf (gtk:file-chooser-select-multiple object) setting)
Arguments:
object -- a gtk:file-chooser widget
setting -- true if multiple files can be selected
Details:
Accessor of the select-multiple slot of the gtk:file-chooser interface. The gtk:file-chooser-select-multiple function gets whether multiple files can be selected in the file selector. The (setf gtk:file-chooser-select-multiple) function sets whether multiple files can be selected. This is only relevant if the action of the file chooser is set to be in :open or :select-folder mode.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26
Accessor gtk:file-chooser-shortcut-folders (object)
Syntax:
(gtk:file-chooser-shortcut-folders object) => folders
Arguments:
object -- a gtk:file-chooser widget
folders -- a g:list-model object of g:file objects
Details:
Accessor of the shortcut-folders slot of the gtk:file-chooser interface. The gtk:file-chooser-shortcut-folders function queries the list of shortcut folders in the file chooser, as set by the gtk:file-chooser-add-shortcut-folder function.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-5-20
Function gtk:file-chooser-current-name (chooser)
Syntax:
(gtk:file-chooser-current-name chooser) => name
(setf (gtk:file-chooser-current-name chooser) name)
Arguments:
chooser -- a gtk:file-chooser widget
name -- a string with the filename to use, as a UTF-8 string
Details:
The gtk:file-chooser-current-name function gets the current name in the file selector, as entered by the user in the text entry for "Name". The (setf gtk:file-chooser-current-name) function sets the current name.

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet. For example, an application that adds a custom extra widget to the file chooser for "file format" may want to change the extension of the typed filename based on the chosen format, say, from ".jpg" to ".png".

Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a "Save As..." dialog. You can pass "Untitled.doc" or a similarly suitable suggestion for the name.

If you want to preselect a particular existing file, you should use the gtk:file-chooser-file function instead. Please see the documentation for this function for an example of using the gtk:file-chooser-current-name function as well.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26
Function gtk:file-chooser-file (chooser)
Syntax:
(gtk:file-chooser-file chooser) => file
(setf (gtk:file-chooser-file chooser) file)
Arguments:
chooser -- a gtk:file-chooser widget
file -- a g:file object for the file
Details:
The gtk:file-chooser-file function gets the g:file object for the currently selected file in the file chooser. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder.

The (setf gtk:file-chooser-file) function sets file as the current filename for the file chooser, by changing to the parent folder of the file and actually selecting the file. If the file chooser is in :save mode, the base name of the file will also appear in the file name entry of the dialog.

If the file name is not in the current folder of the file chooser, then the current folder of the file chooser will be changed to the folder containing file.

Note that the file must exist, or nothing will be done except for the directory change.
Examples:
If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save. For example, when the user opens an existing file and then does "File/Save As..." on it. If you do not have a file name already - for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this:
(if document-is-new
    (progn
      ;; the user just created a new document
      (setf (gtk:file-chooser-current-folder-file chooser)
            default-file-for-saving)
      (setf (gtk:file-chooser-current-name chooser) "Untitled document"))
      (progn
        ;; the user edited an existing document
        (setf (gtk:file-chooser-file chooser) existing-file)))    
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-11-21
Function gtk:file-chooser-namestring (chooser)
Syntax:
(gtk:file-chooser-namestring chooser) => path
(setf (gtk:file-chooser-namestring chooser) path)
Arguments:
chooser -- a gtk:file-chooser widget
path -- a pathname or a namestring for the file
Details:
The gtk:file-chooser-namestring function gets the namestring for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder.

The (setf gtk:file-chooser-namestring) function sets namestring as the current file for the file chooser, by changing to the file's parent folder and actually selecting the file in list. If the chooser is in :save mode, the file's base name will also appear in the dialog's file name entry.
Lisp implementation:
This function corresponds to the gtk:file-chooser-file function, but has a Lisp namestring as an argument for the file. The type conversion between a g:file object and a namestring is automatically done with the g:file-as-namestring type specifier.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-11-21
Function gtk:file-chooser-files (chooser)
Arguments:
chooser -- a gtk:file-chooser widget
Returns:
The g:list-model object containing a g:file object for each selected file and subfolder in the current folder.
Details:
Lists all the selected files and subfolders in the current folder of the file chooser as a list of g:file objects.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2023-8-22
Function gtk:file-chooser-current-folder (chooser)
Syntax:
(gtk:file-chooser-current-folder chooser) => path
(setf (gtk:file-chooser-current-folder chooser) path)
Arguments:
chooser -- a gtk:file-chooser widget
path -- a pathname or namestring with the full path of the new current folder
Details:
The gtk:file-chooser-current-folder function gets the current folder of the file chooser as a local filename. The (setf gtk:file-chooser-current-folder) function sets the current folder.

The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders.

Note that this is the folder that the file chooser is currently displaying, for example, /home/username/Documents, which is not the same as the currently selected folder if the chooser is in :select-folder mode, for example, /home/username/Documents/selected-folder/.

In general, you should not use this function. See the section on setting up a file chooser dialog for the rationale behind this.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-11-21
Function gtk:file-chooser-add-filter (chooser filter)
Arguments:
chooser -- a gtk:file-chooser widget
filter -- a gtk:file-filter object
Details:
Adds a file filter to the list of filters that the user can select between. When a file filter is selected, only files that are passed by that filter are displayed.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2023-8-22
Function gtk:file-chooser-remove-filter (chooser filter)
Arguments:
chooser -- a gtk:file-chooser widget
filter -- a gtk:file-filter object
Details:
Removes a filter from the list of filters that the user can select between.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
#2023-8-22
Function gtk:file-chooser-add-shortcut-folder (chooser folder)
Arguments:
chooser -- a gtk:file-chooser widget
folder -- a namestring with a filename of the folder to add
Returns:
True if the folder could be added successfully, false otherwise.
Details:
Adds a folder to be displayed with the shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a "/usr/share/mydrawprogram/Clipart" folder to the volume list.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
#2024-11-21
Function gtk:file-chooser-remove-shortcut-folder (chooser folder)
Arguments:
chooser -- a gtk:file-chooser widget
folder -- a namestring with the filename of the folder to remove
Returns:
True if the operation succeeds, false otherwise.
Details:
Removes a folder from a file chooser's list of shortcut folders. See also the gtk:file-chooser-add-shortcut-folder function.
Warning:
The gtk:file-chooser implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
#2024-11-21

GtkFileChooserWidget

Class gtk:file-chooser-widget
Superclasses:
Documented Subclasses:
None
Direct Slots:
search-mode
The search-mode property of type :boolean (Read / Write)
The search mode.
Default value: false
show-time
The show-time property of type :boolean (Read)
Whether to show the time. Since 4.10
Default value: false
subtitle
The subtitle property of type :string (Read)
The subtitle.
Default value: ""
Returned by:
Slot Access Functions:
Details:
The gtk:file-chooser-widget widget is a widget for choosing files. It exposes the gtk:file-chooser interface, and you should use the methods of this interface to interact with the widget.
CSS nodes:
The gtk:file-chooser-widget implementation has a single CSS node with name filechooser.
Warning:
The gtk:file-chooser-widget class is deprecated since 4.10. Direct use of the widget is deprecated.
Signal Details:
The "desktop-folder" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show the user's Desktop folder in the file list. The default binding for this signal is the Alt+D key.
The "down-folder" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser go to a child of the current folder in the file hierarchy. The subfolder that will be used is displayed in the path bar widget of the file chooser. For example, if the path bar is showing "/foo/bar/baz", with bar currently displayed, then this will cause the file chooser to switch to the "baz" subfolder. The default binding for this signal is the Alt+Down key.
The "home-folder" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show the user's home folder in the file list. The default binding for this signal is the Alt+Home key.
The "location-popup" signal
lambda (widget path)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
path
The string that gets put in the text entry for the file name.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default bindings for this signal are the Control+L key with a path string of "" (the empty string). It is also bound to / with a path string of "/" (a slash): this lets you type / and immediately type a path name. On Unix systems, this is bound to ~ (tilde) with a path string of "~" itself for access to home directories.
The "location-popup-on-paste" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show a "Location" prompt when the user pastes into a gtk:file-chooser-widget widget. The default binding for this signal is the Control+V key.
The "location-toggle-popup" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to toggle the visibility of a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default binding for this signal is the Control+L key.
The "places-shortcut" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to move the focus to the places sidebar. The default binding for this signal is the Alt+P key.
The "quick-bookmark" signal
lambda (widget index)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
index
The integer with the number of the bookmark to switch to.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser switch to the bookmark specified in the index parameter. For example, if you have three bookmarks, you can pass 0, 1, 2 to this signal to switch to each of them, respectively. The default binding for this signal is the Alt+1 key, the Alt+2 key, etc. until the Alt+0 key. Note that in the default binding, that the Alt+1 key is actually defined to switch to the bookmark at index 0, and so on successively. The Alt+0 key is defined to switch to the bookmark at index 10.
The "recent-shortcut" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show the Recent location. The default binding for this signal is the Alt+R.
The "search-shortcut" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser show the search entry. The default binding for this signal is the Alt+S key.
The "show-hidden" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser display hidden files. The default binding for this signal is the Control+H key.
The "up-folder" signal
lambda (widget)    :action      
widget
The gtk:file-chooser-widget object which received the signal.
A keybinding signal which gets emitted when the user asks for it. This is used to make the file chooser go to the parent of the current folder in the file hierarchy. The default binding for this signal is the Alt+Up key.
See also:
2023-8-30
Accessor gtk:file-chooser-widget-search-mode (object)
Syntax:
(gtk:file-chooser-widget-search-mode object) => mode
(setf (gtk:file-chooser-widget-search-mode object) mode)
Arguments:
object -- a gtk:file-chooser-widget widget
mode -- a boolean whether in search mode
Details:
Accessor of the search-mode slot of the gtk:file-chooser-widget class.
Warning:
The gtk:file-chooser-widget implementation is deprecated since 4.10.
See also:
2024-3-8
Accessor gtk:file-chooser-widget-show-time (object)
Syntax:
(gtk:file-chooser-widget-show-time object) => setting
Arguments:
object -- a gtk:file-chooser-widget widget
setting -- a boolean whether in search mode
Details:
Accessor of the show-time slot of the gtk:file-chooser-widget class.

Since 4.10
Warning:
The gtk:file-chooser-widget implementation is deprecated since 4.10.
See also:
2024-3-8
Accessor gtk:file-chooser-widget-subtitle (object)
Syntax:
(gtk:file-chooser-widget-subtitle object) => subtitle
Arguments:
object -- a gtk:file-chooser-widget widget
subtitle -- a string with the subtitle
Details:
Accessor of the subtitle slot of the gtk:file-chooser-widget class.
Warning:
The gtk:file-chooser-widget implementation is deprecated since 4.10.
See also:
2024-3-8
Function gtk:file-chooser-widget-new (action)
Arguments:
action -- a gtk:file-chooser-action value for open or save mode
Returns:
The new gtk:file-chooser-widget widget.
Details:
Creates a new file chooser widget. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by the gtk:file-chooser-dialog widget.
Warning:
The gtk:file-chooser-widget implementation is deprecated since 4.10.
See also:
2024-3-8

GtkFileChooserDialog

Class gtk:file-chooser-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The gtk:file-chooser-dialog widget is a dialog suitable for use with "File/Open" or "File/Save as" commands. This widget works by putting a gtk:file-chooser-widget widget inside a gtk:dialog widget. It exposes the gtk:file-chooser interface, so you can use all of the gtk:file-chooser functions on the file chooser dialog as well as those for the gtk:dialog widget.

Figure: GtkFileChooserDialog

Note that the gtk:file-chooser-dialog widget does not have any methods of its own. Instead, you should use the functions that work on a gtk:file-chooser interface.

If you want to integrate well with the platform you should use the gtk:file-chooser-native API, which will use a platform-specific dialog if available and fall back to the gtk:file-chooser-dialog widget otherwise.
Setting up a file chooser dialog:
There are various cases in which you may need to use a gtk:file-chooser-dialog widget:
  • To select a file for opening, as for a File/Open command. Use :open.
  • To save a file for the first time, as for a File/Save command. Use :save, and suggest a name such as "Untitled" with the gtk:file-chooser-current-name function.
  • To save a file under a different name, as for a File/Save As command. Use :save, and set the existing filename with the gtk:file-chooser-file function.
  • To choose a folder instead of a file. Use :select-folder.
In general, you should only cause the file chooser to show a specific folder when it is appropriate to use the gtk:file-chooser-file function, that is, when you are doing a "Save As" command and you already have a file saved somewhere.
Response Codes:
The gtk:file-chooser-dialog widget inherits from the gtk:dialog widget, so buttons that go in its action area have response codes such as :accept and :cancel. For example, you could call the gtk:file-chooser-dialog-new function as follows:
(let ((dialog (gtk:file-chooser-dialog-new "Open File"
                                           parent-window
                                           :open
                                           "Cancel" :cancel
                                           "Open" :accept)))
  ... )    
This will create buttons for "Cancel" and "Open" that identifiers from the gtk:response-type enumeration. For most dialogs you can use your own custom response codes rather than the ones in the gtk:response-type enumeration, but the gtk:file-chooser-dialog widget assumes that its "accept"-type action, for example, an "Open" or "Save" button, will have one of the following response codes:
  :accept  :ok  :yes  :apply    
This is because the gtk:file-chooser-dialog widget must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate - the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a predefined response code when you use the gtk:file-chooser-dialog widget to ensure proper operation.
Examples:
Typical usage: In the simplest of cases, you can the following code to use the gtk:file-chooser-dialog widget to select a file for opening:
(defun create-file-chooser-dialog-open (window)
  (let ((dialog (gtk:file-chooser-dialog-new "Open File"
                                             window
                                             :open
                                             "Cancel" :cancel
                                             "Open" :accept)))
    (if (eq :accept (gtk:dialog-run dialog))
      (let ((filename (gtk:file-chooser-filename dialog)))
        ...
      ))
    (gtk:window-destroy dialog)))    
To use a dialog for saving, you can use this:
(defun create-file-chooser-dialog-save (window filename)
  (let ((dialog (gtk:file-chooser-dialog-new "Save File"
                                             window
                                             :save
                                             "Cancel" :cancel
                                             "Save" :accept)))
    (setf (gtk:file-chooser-do-overwrite-confirmation dialog) t)
    (if filename
        (setf (gtk:file-chooser-filename dialog) filename)
        (setf (gtk:file-chooser-current-name dialog) "Untitled document"))
    (if (eq :accept (gtk:dialog-run dialog))
      (let ((filename (gtk:file-chooser-filename dialog)))
        ...
      ))
    (gtk:window-destroy dialog)))    
CSS nodes:
The gtk:file-chooser-dialog implementation has a single CSS node with the name window and .filechooser style class.
Warning:
The gtk:file-chooser-dialog implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-7-30
Function gtk:file-chooser-dialog-new (title parent action &rest buttons)
Arguments:
title -- a string with the title of the dialog, or nil
parent -- a gtk:window transient parent window of the dialog, or nil
action -- a gtk:file-chooser-action value
buttons -- pairs with a button text and the response ID of type gtk:response-type for the button
Returns:
The new gtk:file-chooser-dialog widget.
Details:
Creates a new file chooser dialog. This function is analogous to the gtk:dialog-new-with-buttons function.
Warning:
The gtk:file-chooser-dialog implementation is deprecated since 4.10. Use the gtk:file-dialog object instead.
See also:
2024-4-26

GtkFileChooserNative

Class gtk:file-chooser-native
Superclasses:
gtk:native-dialog, gtk:file-chooser, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
accept-label
The accept-label property of type :string (Read / Write)
The text used for the label on the accept button in the dialog, or nil to use the default text.
Default value: nil
cancel-label
The cancel-label property of type :string (Read / Write)
The text used for the label on the cancel button in the dialog, or nil to use the default text.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The gtk:file-chooser-native class is an abstraction of a dialog suitable for use with "File Open" or "File Save as" commands. By default, this just uses a gtk:file-chooser-dialog widget to implement the actual dialog. However, on certain platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access such as Flatpak, the gtk:file-chooser-native object may call the proper APIs (portals) to let the user choose a file and make it available to the application.

While the API of the gtk:file-chooser-native object closely mirrors the gtk:file-chooser-dialog widget, the main difference is that there is no access to any gtk:window or gtk:widget object for the dialog. This is required, as there may not be one in the case of a platform native dialog.

Showing, hiding and running the dialog is handled by the gtk:native-dialog functions.
Response Codes:
The gtk:file-chooser-native class inherits from the gtk:native-dialog class, which means it will return the :accept value if the user accepted, and the :cancel value if the user pressed cancel. It can also return the :delete-event value if the window was unexpectedly closed.
Differences from GtkFileChooserDialog:
There are a few things in the gtk:file-chooser API that are not possible to use with the gtk:file-chooser-native widget, as such use would prohibit the use of a native dialog.

No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.

Win32 details
On windows the IFileDialog implementation, added in Windows Vista, is used. It supports many of the features that the gtk:file-chooser-dialog widget does, but there are some things it does not handle:
  • Any GtkFileFilter added using a mimetype.
If any of these features are used the regular gtk:file-chooser-dialog widget will be used in place of the native one.

Portal details
When the org.freedesktop.portal.FileChooser portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK file chooser.

macOS details
On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by the gtk:file-chooser-dialog widget are not supported:
  • Shortcut folders.
Examples:
In the simplest of cases, you can use the following code to use the gtk:file-chooser-dialog widget to select a file for opening:
(defun create-file-chooser-native (&optional parent)
  (let ((native (gtk:file-chooser-native-new "Open File"
                                             parent
                                             :open
                                             "_Open"
                                             "_Cancel")))
    ;; Connect a signal handler
    (g:signal-connect native "response"
        (lambda (dialog response)
          (when (eq :accept
                    (gtk:response-type-keyword response))
            (let* ((file (gtk:file-chooser-file dialog))
                   (launcher (gtk:file-launcher-new file)))
              ;; Open the file
              (gtk:file-launcher-launch launcher parent nil
                  (lambda (source result)
                    (declare (ignore source result))
                    (format t "Opened the file ~a~%"
                              (g:file-basename file))))))))
    ;; Show the native file chooser
    (gtk:native-dialog-show native)))    
For more information on how to best set up a file dialog, see the gtk:file-chooser-dialog widget.
Warning:
The gtk:file-chooser-native implementation is deprecated since 4.10. Use the gtk:file-dialog implementation instead.
See also:
2024-5-22
Accessor gtk:file-chooser-native-accept-label (object)
Syntax:
(gtk:file-chooser-native-accept-label object) => label
(setf (gtk:file-chooser-native-accept-label object) label)
Arguments:
object -- a gtk:file-chooser-native object
label -- a string with the custom label or nil for the default
Details:
Accessor of the accept-label slot of the gtk:file-chooser-native interface. The gtk:file-chooser-native-accept-label function retrieves the custom label text for the accept button. The (setf gtk:file-chooser-native-accept-label) function sets the custom label text.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use "__" (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.
Warning:
The gtk:file-chooser-native implementation is deprecated since 4.10. Use the gtk:file-dialog implementation instead.
See also:
2024-4-26
Accessor gtk:file-chooser-native-cancel-label (object)
Syntax:
(gtk:file-chooser-native-cancel-label object) => label
(setf (gtk:file-chooser-native-cancel-label object) label)
Arguments:
object -- a gtk:file-chooser-native object
label -- a string with the custom label or nil for the default
Details:
Accessor of the cancel-label slot of the gtk:file-chooser-native interface. The gtk:file-chooser-native-cancel-label function retrieves the custom label text for the cancel button. The (setf gtk:file-chooser-native-cancel-label) function sets the custom label text.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use "__" (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.
Warning:
The gtk:file-chooser-native implementation is deprecated since 4.10. Use the gtk:file-dialog implementation instead.
See also:
2024-4-26
Function gtk:file-chooser-native-new (title parent action accept-label cancel-label)
Arguments:
title -- a string with the title of the native file chooser
parent -- a gtk:window transient parent window
action -- a gtk:file-chooser-action value
accept-label -- a string with the text to go in the accept button, or nil for the default
cancel-label -- a string with the text to go in the cancel button, or nil for the default
Returns:
The new gtk:file-chooser-native object.
Details:
Creates a new gtk:file-chooser-native object.
Warning:
The gtk:file-chooser-native implementation is deprecated since 4.10. Use the gtk:file-dialog implementation instead.
See also:
2024-4-26

GtkFontChooser

GFlags gtk:font-chooser-level
Declaration:
(gobject:define-gflags "GtkFontChooserLevel" font-chooser-level
  (:export t
   :type-initializer "gtk_font_chooser_level_get_type")
  (:family 0)
  (:style      #.(ash 1 0))
  (:size       #.(ash 1 1))
  (:variations #.(ash 1 2))
  (:features   #.(ash 1 3)))  
Values:
:family
Allow selecting a font family.
:style
Allow selecting a specific font face.
:size
Allow selecting a specific font size.
:variations
Allow changing OpenType font variation axes.
:features
Allow selecting specific OpenType font features.
Details:
The gtk:font-chooser-level flags specifies the granularity of font selection that is desired in a font chooser. Applications should ignore unknown values.
See also:
2024-5-22
Interface gtk:font-chooser
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
font
The font property of type :string (Read / Write)
The font description as a string, for example, "Sans Italic 12".
Default value: "Sans 12"
font-desc
The font-desc property of type pango:font-description (Read / Write)
The Pango font description.
font-features
The font-features property of type :string (Read)
The selected font features, in a format that is compatible with CSS and with Pango attributes.
Default value: nil
language
The language property of type :string (Read / Write)
The language for which the font-features property were selected, in a format that is compatible with CSS and with Pango attributes.
level
The level property of type gtk:font-chooser-level (Read / Write)
The level of granularity to offer for selecting fonts.
Default value: '(:STYLE :SIZE)
preview-text
The preview-text property of type :string (Read / Write)
The string with which to preview the font.
Default value: nil
show-preview-entry
The show-preview-entry property of type :boolean (Read / Write)
Whether to show an entry to change the preview text.
Default value: true
Slot Access Functions:
Details:
The gtk:font-chooser interface is an interface that can be implemented by widgets displaying the list of fonts. In GTK, the main widgets that implement this interface are the gtk:font-chooser-widget, gtk:font-chooser-dialog and gtk:font-button widgets.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
Signal Details:
The "font-activated" signal
lambda (fontchooser fontname)    :run-first      
fontchooser
The gtk:font-chooser widget which received the signal.
fontname
The string with the font name.
Emitted when a font is activated. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the Space, Shift+Space, Return or Enter keys.
See also:
2024-5-22
Accessor gtk:font-chooser-font (object)
Syntax:
(gtk:font-chooser-font object) => fontname
(setf (gtk:font-chooser-font object) fontname)
Arguments:
object -- a gtk:font-chooser object
fontname -- a string with the font name like "Helvetica 12" or "Times Bold 18"
Details:
Accessor of the font slot of the gtk:font-chooser class. The gtk:font-chooser-font function gets the currently selected font name. The (setf gtk:font-chooser-font) function sets the font name.

Note that this can be a different string than what you set with the (setf gtk:font-chooser-font) function, as the font chooser widget may normalize the font names and thus return a string with a different structure. For example, "Helvetica Italic Bold 12" could be normalized to "Helvetica Bold Italic 12".

Use the pango:font-description-equal function if you want to compare two font descriptions.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2023-8-28
Accessor gtk:font-chooser-font-desc (object)
Syntax:
(gtk:font-chooser-font-desc object) => font-desc
(setf (gtk:font-chooser-font-desc object) font-desc)
Arguments:
object -- a gtk:font-chooser object
font-desc -- a pango:font-description instance
Details:
Accessor of the font-desc slot of the gtk:font-chooser class. The gtk:font-chooser-font-desc function gets the Pango font description for the currently selected font. The (setf gtk:font-chooser-font-desc) function sets the currently selected font.

Use the pango:font-description-equal function if you want to compare two Pango font descriptions.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2023-8-28
Accessor gtk:font-chooser-font-features (object)
Syntax:
(gtk:font-chooser-font-features object) => features
Arguments:
object -- a gtk:font-chooser object
features -- a string with the currently selected font features
Details:
Accessor of the font-features slot of the gtk:font-chooser class. The gtk:font-chooser-font-features function gets the currently selected font features, in a format that is compatible with CSS and with Pango attributes. The (setf gtk:font-chooser-font-features) function sets the font features.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2023-8-28
Accessor gtk:font-chooser-language (object)
Syntax:
(gtk:font-chooser-language object) => language
(setf (gtk:font-chooser-language object) language)
Arguments:
object -- a gtk:font-chooser object
language -- a RFC-3066 format string representing the language
Details:
Accessor of the language slot of the gtk:font-chooser class. The gtk:font-chooser-language function gets the language that is used for font features. The (setf gtk:font-chooser-language) function sets the language. See the pango:language-to-string function.
Examples:
(gtk:font-chooser-language (make-instance 'gtk:font-button)) => "de-de"    
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2024-5-22
Accessor gtk:font-chooser-level (object)
Syntax:
(gtk:font-chooser-level object) => level
(setf (gtk:font-chooser-level object) level)
Arguments:
object -- a gtk:font-chooser object
level -- a gtk:font-chooser-level value for the desired level of granularity of type
Details:
Accessor of the level slot of the gtk:font-chooser class. The gtk:font-chooser-level function returns the current level of granularity for selecting fonts. The (setf gtk:font-chooser-level) function sets the desired level of granularity for selecting fonts.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2024-5-22
Accessor gtk:font-chooser-preview-text (object)
Syntax:
(gtk:font-chooser-preview-text object) => text
(setf (gtk:font-chooser-preview-text object) text)
Arguments:
object -- a gtk:font-chooser object
text -- a string with the text to display in the preview area
Details:
Accessor of the preview-text slot of the gtk:font-chooser class. The gtk:font-chooser-preview-text function gets the text displayed in the preview area. The (setf gtk:font-chooser-preview-text) function sets the text displayed in the preview area. The text is used to show how the selected font looks. See the pango:language-sample-string function.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2023-8-28
Accessor gtk:font-chooser-show-preview-entry (object)
Syntax:
(gtk:font-chooser-show-preview-entry object) => show-entry
(setf (gtk:font-chooser-show-preview-entry object) show-entry)
Arguments:
object -- a gtk:font-chooser object
show-entry -- a boolean whether to show the editable preview entry or not
Details:
Accessor of the show-preview-entry slot of the gtk:font-chooser class. Shows or hides the editable preview entry.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
2023-8-28
Function gtk:font-chooser-font-family (fontchooser)
Arguments:
fontchooser -- a gtk:font-chooser object
Returns:
The pango:font-family object representing the selected font family, or nil.
Details:
Gets the Pango font family representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns nil.
Examples:
(defvar fontbutton (make-instance 'gtk:font-button :font "Serif Bold 10"))
=> FONTBUTTON
(gtk:font-chooser-font-family fontbutton)
=> #<PANGO-FONT-FAMILY {1002728D63}>
(pango:font-family-name *)
=> "Sans"    
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
#2024-5-22
Function gtk:font-chooser-font-face (fontchooser)
Arguments:
fontchooser -- a gtk:font-chooser object
Returns:
The pango:font-face object representing the selected font group details, or nil.
Details:
Gets the Pango font face representing the selected font group details, for example, family, slant, weight, width, etc. If the selected font is not installed, returns nil.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
#2024-5-22
Function gtk:font-chooser-font-size (fontchooser)
Arguments:
fontchooser -- a gtk:font-chooser object
Returns:
The integer representing the selected font size in Pango units, or -1 if no font size is selected.
Details:
The selected font size.
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
#2024-5-22
Callback gtk:font-filter-func
Syntax:
lambda (family face) => result
Arguments:
family -- a pango:font-family object
face -- a pango:font-face object belonging to family
result -- true if the font should be displayed
Details:
The callback function that is used for deciding what fonts get shown in a gtk:font-chooser widget. See the gtk:font-chooser-set-filter-func function.
See also:
#2024-5-22
Function gtk:font-chooser-set-filter-func (fontchooser func)
Arguments:
fontchooser -- a gtk:font-chooser object
filter -- a gtk:font-filter-func callback, or nil
Details:
Adds a filter function that decides which fonts to display in the font chooser.
Examples:
A callback filter function to select fonts from the font families "Sans" and "Serif":
;; Define the callback function
(defun font-filter (family face)
  (declare (ignore face))
  (member (pango:font-family-name family)
          '("Sans" "Serif")
          :test #'equal))
;; Set the function FONT-FILTER as the callback function
(gtk:font-chooser-set-filter-func button #'font-filter)
;; Remove the filter function from the font button
(gtk:font-chooser-set-filter-func button nil)    
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
#2024-5-22
Function gtk:font-chooser-font-map (fontchooser)
Syntax:
(gtk:font-chooser-font-map fontchooser) => fontmap
(setf (gtk:font-chooser-font-map fontchooser) fontmap)
Arguments:
fontchooser -- a gtk:font-chooser widget
fontmap -- a pango:font-map object, or nil
Details:
Accessor of the Pango font map of the font chooser widget. The gtk:font-chooser-font-map function gets the custom font map of the font chooser widget, or nil if it does not have one. The (setf gtk:font-chooser-font-map) function sets a custom font map to use for the font chooser widget. A custom font map can be used to present application specific fonts instead of or in addition to the normal system fonts.
Examples:
Note that other GTK widgets will only be able to use the application specific font if it is present in the font map they use. The following code updates the font map for a gtk:label widget with fontmap.
(setf (pango:context-font-map (gtk:widget-pango-context label)) fontmap)    
Warning:
The gtk:font-chooser implementation is deprecated since 4.10. Use the gtk:font-dialog and gtk:font-dialog-button widgets instead.
See also:
#2024-5-22

GtkFontChooserWidget

Class gtk:font-chooser-widget
Superclasses:
Documented Subclasses:
None
Direct Slots:
tweak-action
The tweak-action property of type g:action (Read)
A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. The action will be enabled or disabled depending on whether the selected font has any features or axes.
Details:
The gtk:font-chooser-widget widget lists the available fonts, styles and sizes, allowing the user to select a font. It is used in the gtk:font-chooser-dialog widget to provide a dialog for selecting fonts.

To set or to get the font which is initially selected, use the gtk:font-chooser-font or gtk:font-chooser-font-desc functions.

To change the text which is shown in the preview area, use the gtk:font-chooser-preview-text function.
CSS nodes:
The gtk:font-chooser-widget class has a single CSS node with name fontchooser.
Warning:
The gtk:font-chooser-widget implementation is deprecated since 4.10. Direct use of the gtk:font-chooser-widget widget is deprecated.
See also:
2024-5-22
Accessor gtk:font-chooser-widget-tweak-action (object)
Syntax:
(gtk:font-chooser-widget-tweak-action object) => action
(setf (gtk:font-chooser-widget-tweak-action object) action)
Arguments:
object -- a gtk:font-chooser-widget widget
action -- a g:action toggle action
Details:
Accessor of the tweak-action slot of the gtk:font-chooser-widget class. A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. The action will be enabled or disabled depending on whether the selected font has any features or axes.
Warning:
The gtk:font-chooser-widget implementation is deprecated since 4.10. Direct use of the gtk:font-chooser-widget widget is deprecated.
See also:
2023-8-28
Function gtk:font-chooser-widget-new ()
Returns:
The new gtk:font-chooser-widget widget.
Details:
Creates a new font chooser widget.
Warning:
The gtk:font-chooser-widget implementation is deprecated since 4.10. Direct use of the gtk:font-chooser-widget widget is deprecated.
See also:
2023-8-28

GtkFontChooserDialog

Class gtk:font-chooser-dialog
Superclasses:
Documented Subclasses:
None
Direct Slots:
None
Details:
The gtk:font-chooser-dialog widget is a dialog for selecting a font. It implements the gtk:font-chooser interface.

Figure: GtkFontChooserDialog
GtkFontChooserDialog as GtkBuildable:
The gtk:font-chooser-dialog implementation of the gtk:buildable interface exposes the buttons with the names select_button and cancel_button.
CSS nodes:
The gtk:font-chooser-dialog implementation has a single CSS node with the name fontchooser and .fontchooser style class.
Warning:
The gtk:font-chooser-dialog implementation is deprecated since 4.10. Use the gtk:font-dialog widget instead.
See also:
2023-8-28
Function gtk:font-chooser-dialog-new (title parent)
Arguments:
title -- a string with the title of the dialog, or nil
parent -- a gtk:window transient parent of the dialog, or nil
Returns:
The new gtk:font-chooser-dialog widget.
Details:
Creates a new font chooser dialog.
Warning:
The gtk:font-chooser-dialog implementation is deprecated since 4.10. Use the gtk:font-dialog widget instead.
See also:
2023-8-28

GtkFontButton

Class gtk:font-button
Superclasses:
Documented Subclasses:
None
Direct Slots:
modal
The font-name property of type :boolean (Read / Write)
Whether the dialog is modal.
Default value: true
title
The title property of type :string (Read / Write)
The title of the font chooser dialog.
Default value: "Pick a Font"
use-font
The use-font property of type :boolean (Read / Write)
If this property is set to true, the label will be drawn in the selected font.
Default value: false
use-size
The use-size property of type :boolean (Read / Write)
If this property is set to true, the label will be drawn with the selected font size.
Default value: false
Returned by:
Slot Access Functions:
Details:
The gtk:font-button widget is a button which displays the currently selected font and allows to open a font chooser dialog to change the font. It is a suitable widget for selecting a font in a preference dialog.

Figure: GtkFontButton
CSS nodes:
The gtk:font-button implementation has a single CSS node with name button and .font style class.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
Signal Details:
The "activate" signal
lambda (fontbutton)    :run-first      
fontbutton
The gtk:font-button widget which received the signal.
Emitted to when the font button is activated. The signal on the gtk:font-button widget is an action signal and emitting it causes the button to present its dialog. Since 4.4
The "font-set" signal
lambda (fontbutton)    :run-first      
fontbutton
The gtk:font-button widget which received the signal.
The signal is emitted when the user selects a font. When handling this signal, use the gtk:font-chooser-font function to find out which font was just selected. Note that this signal is only emitted when the user changes the font. If you need to react to programmatic font changes as well, use the "notify::font-name" signal.
See also:
2024-5-22
Accessor gtk:font-button-modal (object)
Syntax:
(gtk:font-button-modal object) => modal
(setf (gtk:font-button-modal object) modal)
Arguments:
object -- a gtk:font-button widget
modal -- a boolean whether the dialog is modal
Details:
Accessor of the modal slot of the gtk:font-button class. The gtk:font-button-modal function gets whether the dialog is modal. The (setf gtk:font-button-modal) funtion sets whether the dialog should be modal.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28
Accessor gtk:font-button-title (object)
Syntax:
(gtk:font-button-title object) => title
(setf (gtk:font-button-title object) title)
Arguments:
object -- a gtk:font-button widget
title -- a string containing the font chooser dialog title
Details:
Accessor of the title slot of the gtk:font-button class. The gtk:font-button-title function retrieves the title of the font chooser dialog. The (setf gtk:font-button-title) function sets the title for the font chooser dialog.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28
Accessor gtk:font-button-use-font (object)
Syntax:
(gtk:font-button-title object) => use-font
(setf (gtk:font-button-title object) use-font)
Arguments:
object -- a gtk:font-button widget
use-font -- if true, font name will be written using font chosen
Details:
Accessor of the use-font slot of the gtk:font-button class. If use-font is true, the font name will be written using the selected font.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28
Accessor gtk:font-button-use-size (object)
Syntax:
(gtk:font-button-use-size object) => use-size
(setf (gtk:font-button-use-size object) use-size)
Arguments:
object -- a gtk:font-button widget
use-size -- if true, the font name will be written using the selected size
Details:
Accessor of the use-size slot of the gtk:font-button class. If use-size is true, the font name will be written using the selected size.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28
Function gtk:font-button-new ()
Returns:
The new gtk:font-button widget.
Details:
Creates a new font picker widget.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28
Function gtk:font-button-new-with-font (fontname)
Arguments:
fontname -- a string with the name of the font to display in the font chooser dialog
Returns:
The new gtk:font-button widget.
Details:
Creates a new font picker widget.
Warning:
The gtk:font-button implementation is deprecated since 4.10. Use the gtk:font-dialog-button widget instead.
See also:
2023-8-28

GtkStyleContext

GFlags gtk:style-context-print-flags
Declaration:
(gobject:define-gflags "GtkStyleContextPrintFlags" style-context-print-flags
  (:export t
   :type-initializer "gtk_style_context_print_flags_get_type")
  (:none 0)
  (:recurse #.(ash 1 0))
  (:show-style #.(ash 1 1))
  (:show-change #.(ash 1 2)))  
Values:
:none
:recurse
Print the entire tree of CSS nodes starting at the node of the style context.
:show-style
Show the values of the CSS properties for each node.
:show-change
Show information about what changes affect the styles.
Details:
Flags that modify the behavior of the gtk:style-context-to-string function. New values may be added to this enumeration.
See also:
2023-8-30
Class gtk:style-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
display
The display property of type gdk:display (Read / Write)
The associated display of the style context.
Slot Access Functions:
Details:
The gtk:style-context object stores styling information affecting a widget. In order to construct the final style information, the gtk:style-context object queries information from all attached gtk:style-provider objects. Style providers can be either attached explicitly to the style context through the gtk:style-context-add-provider function, or to the display through the gtk:style-context-add-provider-for-display function. The resulting style is a combination of all information of the style provider in priority order.

For GTK widgets, any gtk:style-context object returned by the gtk:widget-style-context function will already have a gdk:display instance and a text direction information set. The style context will be also updated automatically if any of these settings change on the widget.

Style Classes
Widgets can add style classes to their style context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance.

Custom styling in UI libraries and applications
If you are developing a library with custom widgets that render differently than standard components, you may need to add a gtk:style-provider object yourself with the gtk:+priority-fallback+ priority, either a gtk:css-provider object or a custom object implementing the gtk:style-provider interface. This way themes may still attempt to style your UI elements in a different way if needed so.

If you are using custom styling on an application, you probably want then to make your style information prevail to the style information of the theme, so you must use a gtk:style-provider object with the gtk:+priority-application+ priority. Keep in mind that the user settings in XDG_CONFIG_HOME/gtk-4.0/gtk.css will still take precedence over your changes, as it uses the gtk:+priority-user+ priority.
Warning:
The gtk:style-context implementation is deprecated since 4.10. The relevant API has been moved to the gtk:widget implementation where applicable. Otherwise, there is no replacement for querying the style machinery. Stylable UI elements should use widgets.
See also:
2023-8-30
Accessor gtk:style-context-display (object)
Syntax:
(gtk:style-context-display object) => display
(setf (gtk:style-context-display object) display)
Arguments:
object -- a gtk:style-context object
display -- a gdk:display object
Details:
Accessor of the display slot of the gtk:style-context class. The gtk:style-context-display function returns the display to which the style context is attached. The (setf gtk:style-context-display) function attaches the style context to the given display.

The display is used to add style information from 'global' style providers, such as the gtk:settings instance of the display. If you are using a gtk:style-context object returned from the gtk:widget-style-context function, you do not need to call this yourself.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-display function instead.
See also:
2023-9-18
Function gtk:style-context-add-provider (context provider priority)
Arguments:
context -- a gtk:style-context object
provider -- a gtk:style-provider object
priority -- an unsigned integer with the priority of the style provider
Details:
Adds a style provider to the style context, to be used in style construction. The lower the priority of the style provider is, the earlier it will be used in the style construction. Typically this will be in the range between the gtk:+priority-fallback+ and gtk:+priority-user+ priorities.

Note that a style provider added by this function only affects the style of the widget to which context belongs. If you want to affect the style of all widgets, use the gtk:style-context-add-provider-for-display function.
Notes:
If both priorities are the same, a style provider object added through this function takes precedence over another added through the gtk:style-context-add-provider-for-display function.
Warning:
This function is deprecated since 4.10. Use style classes instead. See the gtk:style-context-add-provider-for-display documentation for an example.
See also:
2023-9-17
Function gtk:style-context-add-provider-for-display (display provider &optional priority)
Arguments:
display -- a gdk:display object
provider -- a gtk:style-provider object
priority -- an optional unsigned integer with the priority of the style provider, the default value is gtk:+priority-application+
Details:
Adds a global style provider to the display, which will be used in style construction for all style contexts under the display. GTK uses this to make styling information from the gtk:settings object available.
Examples:
Change the color and the font in a text view: Create a provider, load CSS into the provider, add the style class and the provider to the parent window.
(let ((provider (gtk:css-provider-new)))
  (gtk:css-provider-load-from-data provider
                                   ".viewstyle textview {
                                      color : Green;
                                      font : 20px Purisa; }")
  (gtk:widget-add-css-class window "viewstyle")
  (gtk:style-context-add-provider-for-display (gtk:widget-display window)
                                              provider)
  ... )    
Notes:
If both priorities are the same, a style provider object added through the gtk:style-context-add-provider function takes precedence over another added through this function.
See also:
2024-4-19
Function gtk:style-context-state (context)
Syntax:
(gtk:style-context-state context) => state
(setf (gtk:style-context-state context) state)
Arguments:
context -- a gtk:style-context object
state -- a value of the gtk:state-flags flags to represent
Details:
Accessor of the state used when rendering. The gtk:style-context-state function returns the state used for style matching. The (setf gtk:style-context-state) function sets the state.

This function should only be used to retrieve the gtk:state-flags values to pass to the gtk:style-context functions, like the gtk:style-context-padding function. If you need to retrieve the current state of a gtk:widget object, use the gtk:widget-state-flags function.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-state-flags function instead.
See also:
#2023-9-18
Function gtk:style-context-color (context)
Arguments:
context -- a gtk:style-context object
Returns:
The gdk:rgba instance with the foreground color.
Details:
Gets the foreground color for a given state.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-color function instead.
See also:
#2023-9-17
Function gtk:style-context-border (context state)
Arguments:
context -- a gtk:style-context object
state -- a gtk:state-flags value to retrieve the border for
Returns:
Returns border settings as a gtk:border instance.
Details:
Gets the value for the border settings for a given state.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-padding (context state)
Arguments:
context -- a gtk:style-context object
state -- a gtk:state-flags value to retrieve the padding for
Returns:
Returns padding settings as a gtk:border instance.
Details:
Gets the value for the padding settings for a given state.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-margin (context state)
Arguments:
context -- a gtk:style-context object
state -- a gtk:state-flags value to retrieve the margin for
Returns:
Returns margin settings as a gtk:border instance.
Details:
Gets the value for the margin settings for a given state.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-lookup-color (context name)
Arguments:
context -- a gtk:style-context object
name -- a string with a color name to lookup
Returns:
The looked up gdk:rgba color, or nil.
Details:
Looks up and resolves a color name in the style context color map.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-remove-provider (context provider)
Arguments:
context -- a gtk:style-context object
provider -- a gtk:style-provider object
Details:
Removes the style provider from the style providers list in the style context.
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:style-context-remove-provider-for-display (display provider)
Arguments:
display -- a gdk:display object
provider -- a gtk:style-provider object
Details:
Removes the style provider from the global style providers list in the display.
See also:
2023-9-17
Function gtk:style-context-restore (context)
Arguments:
context -- a gtk:style-context object
Details:
Restores the style context state to a previous stage. See the gtk:style-context-save function.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-save (context)
Arguments:
context -- a gtk:style-context object
Details:
Saves the style context state. So all modifications done through the gtk:style-context-add-class, gtk:style-context-remove-class or gtk:style-context-state functions can be reverted in one go through the gtk:style-context-restore function.
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
#2023-9-17
Function gtk:style-context-add-class (context classname)
Arguments:
context -- a gtk:style-context object
classname -- a string with a class name to use in styling
Details:
Adds a style class to the style context, so later uses of the style context will make use of this new class for styling.
Examples:
In the CSS file format, a GtkEntry defining an "entry" class, would be matched by:
GtkEntry.entry { ... }  
While any widget defining an "entry" class would be matched by:
.entry { ... }    
Warning:
This function is deprecated since 4.10. Use the gtk:widget-add-css-class function instead.
See also:
#2023-9-17
Function gtk:style-context-remove-class (context classname)
Arguments:
context -- a gtk:style-context object
classname -- a string with a class name to remove
Details:
Removes a class name from the style context.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-remove-css-class function instead.
See also:
#2023-9-17
Function gtk:style-context-has-class (context classname)
Arguments:
context -- a gtk:style-context object
classname -- a string with a class name
Returns:
True if the style context has classname defined.
Details:
Returns true if the style context currently has defined the given class name.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-has-css-class function instead.
See also:
gtk:style-context
gtk:widget-hass-css-class
#2023-9-17
Function gtk:style-context-scale (context)
Syntax:
(gtk:style-context-scale context) => scale
(setf (gtk:style-context-scale context) scale)
Arguments:
context -- a gtk:style-context object
scale -- an integer with a scale
Details:
Accessor of the scale used for image assets for the style context. The gtk:style-context-scale function returns the scale to use when getting image assets for the style. The (setf gtk:style-context-scale) function sets the scale.
Warning:
This function is deprecated since 4.10. Use the gtk:widget-scale-factor function instead.
See also:
#2023-9-18
Function gtk:style-context-to-string (context flags)
Arguments:
context -- a gtk:style-context object
flags -- a gtk:style-context-print-flags value that determine what to print
Returns:
The string representing the style context.
Details:
Converts the style context into a string representation. The string representation always includes information about the name, state, ID, visibility and style classes of the CSS node that is backing the style context. Depending on the flags, more information may be included.

This function is intended for testing and debugging of the CSS implementation in GTK. There are no guarantees about the format of the returned string, it may change.
Examples:
(setq context
      (gtk:widget-style-context (make-instance 'gtk:dialog)))
=> #<GTK:STYLE-CONTEXT {1001C70663}>
(gtk:style-context-to-string context :recurse)
=>
"[window.background.dialog:dir(ltr)]
  box.dialog-vbox.vertical:dir(ltr)
    box.vertical:dir(ltr)
    box.dialog-action-box.horizontal:dir(ltr)
      box.dialog-action-area.horizontal:dir(ltr)
"    
Warning:
This function is deprecated since 4.10. This API will be removed in GTK 5.
See also:
2024-10-13
GBoxed gtk:border
Declaration:
(glib:define-gboxed-cstruct border "GtkBorder"
  (:export t
   :type-initializer "gtk_border_get_type")
  (left :int16 :initform 0)
  (right :int16 :initform 0)
  (top :int16 :initform 0)
  (bottom :int16 :initform 0))  
Values:
left
The width of the left border.
right
The width of the right border.
top
The width of the top border.
bottom
The width of the bottom border.
Returned by:
Slot Access Functions:
Details:
A structure that specifies a border around a rectangular area that can be of different width on each side.
2023-8-30
Accessor gtk:border-left (instance)
Syntax:
(gtk:border-left instance) => left
(setf (gtk:border-left instance) left)
Arguments:
instance -- a gtk:border instance
left -- an integer with the width of the left border
Details:
Accessor of the left slot of the gtk:border structure.
See also:
2023-8-30
Accessor gtk:border-right (instance)
Syntax:
(gtk:border-right instance) => right
(setf (gtk:border-right instance) right)
Arguments:
instance -- a gtk:border instance
right -- an integer with the width of the right border
Details:
Accessor of the right slot of the gtk:border structure.
See also:
2023-8-30
Accessor gtk:border-top (instance)
Syntax:
(gtk:border-top instance) => top
(setf (gtk:border-top instance) top)
Arguments:
instance -- a gtk:border instance
top -- an integer with the width of the top border
Details:
Accessor of the top slot of the gtk:border structure.
See also:
2023-8-30
Accessor gtk:border-bottom (instance)
Syntax:
(gtk:border-top instance) => bottom
(setf (gtk:border-top instance) bottom)
Arguments:
instance -- a gtk:border instance
bottom -- an integer with the width of the bottom border
Details:
Accessor of the bottom slot of the gtk:border structure.
See also:
2023-8-30
Function gtk:border-new (&key left right top bottom)
Arguments:
left -- an integer with the width of the left border
right -- an integer with the width of the right border
top -- an integer with the width of the top border
bottom -- an integer with the width of the bottom border
Returns:
The newly allocated gtk:border instance.
Details:
Allocates a new gtk:border instance and initializes its elements.
See also:
2023-8-30
Function gtk:border-copy (border)
Arguments:
border -- a gtk:border instance
Returns:
The gtk:border instance with the copy of border.
Details:
Copies a gtk:border instance.
See also:
2023-8-30
Function gtk:render-activity (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the rectangle
y -- a number, coerced to a double float, with the y origin of the rectangle
width -- a number, coerced to a double float, with the rectangle width
height -- a number, coerced to a double float, with the rectangle height
Details:
Renders an activity area such as in the gtk:spinner widget or the fill line in the gtk:range widget. The :active state of the gtk:state-flags flags determines whether there is activity going on.
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-arrow (context cr angle x y size)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
angle -- a number, coerced to a double float, with an arrow angle from 0 to 2 * Pi, being 0 the arrow pointing to the north
x -- a number, coerced to a double float, with the x origin of the render area
y -- a number, coerced to a double float, with the y origin of the render area
size -- a number, coerced to a double float, with the square side for render area
Details:
Renders an arrow pointing to an angle.

Typical arrow rendering at 0, 1/2 Pi, Pi, and 3/2 Pi:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-background (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the render area
y -- a number, coerced to a double float, with the y origin of the render area
width -- a number, coerced to a double float, with the rectangle width
height -- a number, coerced to a double float, with the rectangle height
Details:
Renders the background of an element.

Typical background rendering, showing the effect of background-image, border-width and border-radius:
Warning:
The function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-check (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the rectangle
y -- a number, coerced to a double float, with the y origin of the rectangle
width -- a number, coerced to a double float, with a rectangle width
height -- a number, coerced to a double float, with a rectangle height
Details:
Renders a checkmark as in a gtk:check-button widget. The :checked state of the gtk:state-flags flags determines whether the check is on or off, and the :inconsistent state determines whether it should be marked as undefined.

Typical checkmark rendering:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-expander (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the rectangle
y -- a number, coerced to a double float, with the y origin of the rectangle
width -- a number, coerced to a double float, with a rectangle width
height -- a number, coerced to a double float, with a rectangle height
Details:
Renders an expander as used in the gtk:tree-view widget and gtk:expander widget in the area defined by x, y, width, height. The :active state of the gtk:state-flags flags determines whether the expander is collapsed or expanded.

Typical expander rendering:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-focus (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with a x origin of the rectangle
y -- a number, coerced to a double float, with a y origin of the rectangle
width -- a number, coerced to a double float, with a rectangle width
height -- a number, coerced to a double float, with a rectangle height
Details:
Renders a focus indicator on the rectangle determined by x, y, width, height.

Typical focus rendering:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-frame (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the rectangle
y -- a number, coerced to a double float, with the y origin of the rectangle
width -- a number, coerced to a double float, with the rectangle width
height -- a number, coerced to a double float, with the rectangle height
Details:
Renders a frame around the rectangle defined by x, y, width, height.

Examples of frame rendering, showing the effect of border-image, border-color, border-width, border-radius and junctions:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-handle (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with a x origin of the rectangle
y -- a number, coerced to a double float, with a y origin of the rectangle
width -- a number, coerced to a double float, with a rectangle width
height -- a number, coerced to a double float, with a rectangle height
Details:
Renders a handle, as the resize grip of the gtk:paned widget and gtk:window widget, in the rectangle determined by x, y, width, height.

Handles rendered for the paned and grip classes:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-icon (context cr texture x y)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
texture -- a gdk:texture object containing the icon to draw
x -- a number, coerced to a double float, with the x position for the texture
y -- a number, coerced to a double float, with the y position for the texture
Details:
Renders the icon in a texture at the specified x and y coordinates. This function will render the icon in texture at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities.
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-layout (context cr x y layout)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with the x origin of the rectangle
y -- a number, coerced to a double float, with the y origin of the rectangle
layout -- a pango:layout object to render
Details:
Renders a Pango layout on the coordinates x, y.
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-line (context cr x0 y0 x1 y1)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x0 -- a number, coerced to a double float, with the x coordinate for the origin of the line
y0 -- a number, coerced to a double float, with the y coordinate for the origin of the line
x1 -- a number, coerced to a double float, with the x coordinate for the end of the line
y1 -- a number, coerced to a double float, with the y coordinate for the end of the line
Details:
Renders a line from (x0,y0) to (x1,y1).
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17
Function gtk:render-option (context cr x y width height)
Arguments:
context -- a gtk:style-context object
cr -- a cairo:context-t context
x -- a number, coerced to a double float, with a x origin of the rectangle
y -- a number, coerced to a double float, with a y origin of the rectangle
width -- a number, coerced to a double float, with a rectangle width
height -- a number, coerced to a double float, with a rectangle height
Details:
Renders an option mark as in a gtk:check-button widget. The :checked state of the gtk:state-flags flags will determine whether the option is on or off, and the :inconsistent state whether it should be marked as undefined.

Typical option mark rendering:
Warning:
This function is deprecated since 4.10. Please do not use it in newly written code.
See also:
#2023-9-17

Other Functions in gtk

Function gtk:widget-get-parent (widget)

No documentation string. Possibly unimplemented or incomplete.

Other Symbols in gtk

Symbol gtk:list-list-model-item-type

No documentation string. Possibly unimplemented or incomplete.

Other Classes in gtk

Class gtk:list-list-model
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
n-items

No documentation string. Possibly unimplemented or incomplete.


Package gdk

GDK is an intermediate layer which isolates GTK from the details of the windowing system. This is the API documentation of a Lisp binding to GDK.

General

Enumerations

GEnum gdk:gravity
Declaration:
(gobject:define-genum "GdkGravity" gravity
  (:export t
   :type-initializer "gdk_gravity_get_type")
  (:north-west 1)
  (:north 1)
  (:north-east 3)
  (:west 4)
  (:center 5)
  (:east 6)
  (:south-west 7)
  (:south 8)
  (:south-east 9)
  (:static 10))  
Values:
:north-west
The reference point is at the top left corner.
:north
The reference point is in the middle of the top edge.
:north-east
The reference point is at the top right corner.
:west
The reference point is at the middle of the left edge.
:center
The reference point is at the center of the surface.
:east
The reference point is at the middle of the right edge.
:south-west
The reference point is at the lower left corner.
:south
The reference point is at the middle of the lower edge.
:sout-east
The reference point is at the lower right corner.
:static
The reference point is at the top left corner of the surface itself, ignoring window manager decorations.
Details:
Defines the reference point of a surface and is used in the gdk:popup-layout implementation.
See also:
2024-5-26
Constant gdk:+modifier-mask+
Initial Value:
'(:shift-mask :lock-mask :control-mask :alt-mask :button1-mask :button2-mask :button3-mask :button4-mask :button5-mask :super-mask :hyper-mask :meta-mask)
Details:
A mask covering all entries in the gdk:modifier-type enumeration.
See also:
2024-5-26
GFlags gdk:modifier-type
Declaration:
(gobject:define-gflags "GdkModifierType" modifier-type
  (:export t
   :type-initializer "gdk_modifier_type_get_type")
  #-gtk-4-14
  (:none 0)
  #+gtk-4-14
  (:no-modifier-mask 0)
  (:shift-mask   #.(ash 1 0))
  (:lock-mask    #.(ash 1 1))
  (:control-mask #.(ash 1 2))
  (:alt-mask     #.(ash 1 3))
  (:button1-mask #.(ash 1 8))
  (:button2-mask #.(ash 1 9))
  (:button3-mask #.(ash 1 10))
  (:button4-mask #.(ash 1 11))
  (:button5-mask #.(ash 1 12))
  (:super-mask   #.(ash 1 26))
  (:hyper-mask   #.(ash 1 27))
  (:meta-mask    #.(ash 1 28)))  
Values:
:no-modifier-mask
No modifier key. Since 4.14
:shift-mask
The Shift key.
:lock-mask
The Lock key, depending on the modifier mapping of the X server this may either be the CapsLock or ShiftLock key.
:control-mask
The Control key.
:alt-mask
The fourth modifier key. It depends on the modifier mapping of the X server which key is interpreted as this modifier, but normally it is the Alt key.
:button1-mask
The first mouse button.
:button2-mask
The second mouse button.
:button3-mask
The third mouse button.
:button4-mask
The fourth mouse button.
:button5-mask
The fifth mouse button.
:super-mask
The Super modifier.
:hyper-mask
The Hyper modifier.
:meta-mask
The Meta modifier.
Details:
Flags to indicate the state of modifier keys and mouse buttons in events. Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock keys.

Note that GDK may add internal values to events which include values outside this enumeration. Your code should preserve and ignore them. You can use the gdk:+modifier-mask+ value to remove all private values.
See also:
2024-5-25

GdkRectangle

GBoxed gdk:rectangle
Declaration:
(glib:define-gboxed-cstruct rectangle "GdkRectangle"
  (:export t
   :type-initializer "gdk_rectangle_get_type")
  (x :int :initform 0)
  (y :int :initform 0)
  (width :int :initform 0)
  (height :int :initform 0))  
Values:
x
The x coordinate of the top left corner.
y
The y coordinate of the top left corner.
width
The width of the rectangle.
height
The height of the rectangle.
Returned by:
Slot Access Functions:
Details:
The gdk:rectangle structure is a data type for representing rectangles. The gdk:rectangle structure is identical to the cairo:rectangle-t structure. Together with the cairo:region-t data type of Cairo, these are the central types for representing sets of pixels.

The intersection of two rectangles can be computed with the gdk:rectangle-intersect function. To find the union of two rectangles use the gdk:rectangle-union function.

The cairo:region-t type provided by Cairo is usually used for managing non-rectangular clipping of graphical operations.

The Graphene library has a number of other data types for regions and volumes in 2D and 3D.
See also:
cairo:region-t
cairo:rectangle-t
2024-7-9
Accessor gdk:rectangle-x (instance)
Syntax:
(gdk:rectangle-x instance) => x
(setf (gdk:rectangle-x instance) x)
Arguments:
instance -- a gdk:rectangle instance
x -- an integer with the x coordinate of the rectangle
Details:
Accessor of the x slot of the gdk:rectangle structure.
See also:
2024-7-9
Accessor gdk:rectangle-y (instance)
Syntax:
(gdk:rectangle-y instance) => y
(setf (gdk:rectangle-y instance) y)
Arguments:
instance -- a gdk:rectangle instance
y -- an integer with the y coordinate of the rectangle
Details:
Accessor of the y slot of the gdk:rectangle structure.
See also:
2024-7-9
Accessor gdk:rectangle-width (instance)
Syntax:
(gdk:rectangle-width instance) => width
(setf (gdk:rectangle-width instance) width)
Arguments:
instance -- a gdk:rectangle instance
width -- an integer with the width of the rectangle
Details:
Accessor of the width slot of the gdk:rectangle structure.
See also:
2024-7-9
Accessor gdk:rectangle-height (instance)
Syntax:
(gdk:rectangle-height instance) => height
(setf (gdk:rectangle-height instance) height)
Arguments:
instance -- a gdk:rectangle instance
height -- an integer with the height of the rectangle
Details:
Accessor of the height slot of the gdk:rectangle structure.
See also:
2024-7-9
Function gdk:rectangle-new (&key x y width height)
Arguments:
x -- an integer with the value for the x slot
y -- an integer with the value for the y slot
width -- an integer with the value for the width slot
height -- an integer with the value for the height slot
Details:
Returns a gdk:rectangle instance with the initial values given to x, y, width, and height.
See also:
2024-7-9
Function gdk:rectangle-copy (instance)
Arguments:
instance -- a gdk:rectangle instance
Details:
Copy constructor of a gdk:rectangle structure.
See also:
2024-7-9
Function gdk:rectangle-contains-point (rect x y)
Arguments:
rect -- a gdk:rectangle instance
x -- an integer with the x coordinate
y -- an integer with the y coordinate
Returns:
True if rect contains the point.
Details:
Returns true if rect contains the point described by x and y.
See also:
2024-7-9
Function gdk:rectangle-equal (rect1 rect2)
Arguments:
rect1 -- a gdk:rectangle instance
rect2 -- a gdk:rectangle instance
Returns:
True if the rectangles are equal.
Details:
Checks if the two given rectangles are equal.
See also:
2024-7-9
Function gdk:rectangle-intersect (rect1 rect2)
Arguments:
rect1 -- a gdk:rectangle instance
rect2 -- a gdk:rectangle instance
Returns:
The gdk:rectangle instance with the intersection of rect1 and rect2, or nil.
Details:
Calculates the intersection of two rectangles. If the rectangles do not intersect nil is returned.
See also:
2024-7-9
Function gdk:rectangle-union (rect1 rect2)
Arguments:
rect1 -- a gdk:rectangle instance
rect2 -- a gdk:rectangle instance
Returns:
The gdk:rectangle instance with the union of rect1 and rect2.
Details:
Calculates the union of two rectangles. The union of rectangles rect1 and rect2 is the smallest rectangle which includes both rectangles within it.
See also:
2024-7-9

GdkRGBA

GBoxed gdk:rgba
Declaration:
(glib:define-gboxed-cstruct rgba "GdkRGBA"
  (:export t
   :type-initializer "gdk_rgba_get_type")
  (red :float :initform 0.0)
  (green :float :initform 0.0)
  (blue :float :initform 0.0)
  (alpha :float :initform 0.0))  
Values:
red
The intensity of the red channel from 0.0 to 1.0 inclusive.
green
The intensity of the green channel from 0.0 to 1.0 inclusive.
blue
The intensity of the blue channel from 0.0 to 1.0 inclusive.
alpha
The opacity of the color from 0.0 for completely translucent to 1.0 for opaque.
Returned by:
Slot Access Functions:
Details:
The gdk:rgba structure is used to represent a (possibly translucent) color, in a way that is compatible with Cairo's notion of color. All values are in the range from 0.0 to 1.0 inclusive. So the color
(gdk:rgba-new :red 0.0 :green 0.0 :blue 0.0 :alpha 0.0)  
represents transparent black and
(gdk:rgba-new :red 1.0 :green 1.0 :blue 1.0 :alpha 1.0)  
is opaque white. Other values will be clamped to this range when drawing.
2025-1-11
Accessor gdk:rgba-red (instance)
Syntax:
(gdk:rgba-red instance) => red
(setf (gdk:rgba-red instance) red)
Arguments:
instance -- a gdk:rgba color
red -- a number coerced to a single float for the intensity of the red channel from 0.0 to 1.0
Details:
Accessor of the red slot of the gdk:rgba color.
See also:
2025-1-11
Accessor gdk:rgba-green (instance)
Syntax:
(gdk:rgba-green instance) => green
(setf (gdk:rgba-green instance) green)
Arguments:
instance -- a gdk:rgba color
green -- a number coerced to a single float for the intensity of the green channel from 0.0 to 1.0
Details:
Accessor of the green slot of the gdk:rgba color.
See also:
2025-1-11
Accessor gdk:rgba-blue (instance)
Syntax:
(gdk:rgba-blue instance) => blue
(setf (gdk:rgba-blue instance) blue)
Arguments:
instance -- a gdk:rgba color
blue -- a number coerced to a single float for the intensity of the blue channel from 0.0 to 1.0
Details:
Accessor of the blue slot of the gdk:rgba color.
See also:
2025-1-11
Accessor gdk:rgba-alpha (instance)
Syntax:
(gdk:rgba-alpha instance) => alpha
(setf (gdk:rgba-alpha instance) alpha)
Arguments:
instance -- a gdk:rgba color
alpha -- a number coerced to a single float for the opacity of the color from 0.0 for completely translucent to 1.0 for opaque
Details:
Accessor of the alpha slot of the gdk:rgba color.
See also:
2025-1-11
Function gdk:rgba-new (&key red green blue alpha)
Arguments:
red -- a number for the intensity of the red channel from 0.0 to 1.0 inclusive
green -- a number for the intensity of the green channel from 0.0 to 1.0 inclusive
blue -- a number for the intensity of the blue channel from 0.0 to 1.0 inclusive
alpha -- a number for the opacity of the color from 0.0 for completely translucent to 1.0 for opaque
Returns:
The newly created gdk:rgba color.
Details:
Creates a gdk:rgba color.
Notes:
All numbers are coerced to a single float before being passed to the foreign C function.
See also:
2025-1-11
Function gdk:rgba-copy (rgba)
Arguments:
rgba -- a gdk:rgba color
Returns:
The newly allocated gdk:rgba color, with the same contents as rgba.
Details:
Makes a copy of a gdk:rgba color.
See also:
2025-1-11
Function gdk:rgba-is-clear (rgba)
Arguments:
rgba -- a gdk:rgba color
Returns:
True if the RGBA color is clear.
Details:
Checks if a RGBA color is transparent. That is, drawing with the color would not produce any change.
See also:
2025-1-11
Function gdk:rgba-is-opaque (rgba)
Arguments:
rgba -- a gdk:rgba color
Returns:
True if the RGBA color is opaque.
Details:
Checks if a RGBA color is transparent. That is, drawing with the color will not retain any results from previous contents.
See also:
2025-1-11
Function gdk:rgba-parse (str)
Arguments:
str -- a string specifying the color
Returns:
The newly created gdk:rgba color with the filled in values, or nil.
Details:
Parses a textual representation of a color, and returns a RGBA instance filling in the red, green, blue and alpha fields. If the given textual representation is not recognized, nil is returned. The string can be either one of:
  • A standard name taken from the X11 rgb.txt file.
  • A hex value in the form rgb, rrggbb, rrrgggbbb or rrrrggggbbbb.
  • A RGB color in the form rgb(r,g,b). In this case the color will have full opacity.
  • A RGBA color in the form rgba(r,g,b,a).
Where r, g, b and a are respectively the red, green, blue and alpha color values. In the last two cases, r, g and b are either integers in the range 0 to 255 or precentage values in the range 0% to 100%, and a is a floating point value in the range 0.0 to 1.0.
Examples:
(gdk:rgba-parse "LightGreen")
=> #S(GDK-RGBA :RED 0.5647059
               :GREEN 0.93333334
               :BLUE 0.5647059
               :ALPHA 1.0)
(gdk:rgba-parse "#90ee90")
=> #S(GDK-RGBA :RED 0.5647059
               :GREEN 0.93333334
               :BLUE 0.5647059
               :ALPHA 1.0)
(gdk:rgba-parse "unknown") => NIL    
See also:
2025-1-11
Function gdk:rgba-hash (color)
Arguments:
color -- a gdk:rgba color
Returns:
The unsigned integer with the hash value for color.
Details:
A hash function suitable for using for a hash table that stores RGBA colors.
See also:
2025-1-11
Function gdk:rgba-equal (color1 color2)
Arguments:
color1 -- a gdk:rgba color
color2 -- another gdk:rgba color
Returns:
True if the two colors compare equal.
Details:
Compares two RGBA colors.
See also:
2025-1-11
Function gdk:rgba-to-string (color)
Arguments:
color -- a gdk:rgba color
Returns:
The string with the textual specification of color.
Details:
Returns a textual specification of color in the form rgb(r,g,b) or rgba(r,g,b,a), where r, g, b and a represent the red, green, blue and alpha values respectively. r, g, and b are represented as integers in the range 0 to 255, and a is represented as a floating point value in the range 0.0 to 1.0.

These string forms are supported by the CSS3 colors module, and can be parsed by the gdk:rgba-parse function.

Note that this string representation may loose some precision, since r, g and b are represented as 8-bit integers. If this is a concern, you should use a different representation.
Examples:
(gdk:rgba-to-string (gdk:rgba-new :red 1.0))
=> "rgba(255,0,0,0)"
(gdk:rgba-parse *)
=> #S(GDK-RGBA :RED 1.0 :GREEN 0.0 :BLUE 0.0 :ALPHA 0.0)    
See also:
2025-1-11

Key Values

Function gdk:keyval-name (keyval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
The string containing the name of the key, or nil if keyval is not a valid key.
Details:
Converts a key value into a symbolic name. The names are the same as those in the gdk/gdkkeysyms.h header file but without the leading GDK_KEY_.
See also:
2024-7-9
Function gdk:keyval-from-name (name)
Arguments:
name -- a string with the key name
Returns:
The unsigned integer with the corresponding key value, or #xffffff if the key name is not a valid key
Details:
Converts a key name to a key value. The names are the same as those in the gdk/gdkkeysyms.h header file but without the leading GDK_KEY_.
See also:
2024-7-9
Function gdk:keyval-convert-case (keyval)
Syntax:
(gdk:keyval-convert-case keyval) => lower, upper
Arguments:
keyval -- an unsigned integer with the key value
lower -- an unsigned integer with the lowercase version of keyval
upper -- an unsigned integer with the uppercase verson of keyval
Details:
Obtains the upper-case and lower-case versions of the key value.
See also:
2024-7-9
Function gdk:keyval-to-upper (keyval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
The unsigned integer with the upper case form of keyval, or keyval itself if it is already in upper case or it is not subject to case conversion.
Details:
Converts a key value to upper case, if applicable.
See also:
2024-7-9
Function gdk:keyval-to-lower (keyval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
The unsigned integer with the lower case form of keyval, or keyval itself if it is already in lower case or it is not subject to case conversion.
Details:
Converts a key value to lower case, if applicable.
See also:
2024-7-9
Function gdk:keyval-is-upper (keyval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
True if keyval is in upper case, or if keyval is not subject to case conversion.
Details:
Returns true if the given key value is in upper case.
See also:
2024-7-9
Function gdk:keyval-is-lower (keval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
True if keyval is in lower case, or if keyval is not subject to case conversion.
Details:
Returns true if the given key value is in lower case.
See also:
2024-7-9
Function gdk:keyval-to-unicode (keyval)
Arguments:
keyval -- an unsigned integer with the key value
Returns:
The unsigned integer with the corresponding unicode character, or 0 if there is no corresponding character.
Details:
Convert from a GDK key value to the corresponding ISO10646 (Unicode) character. Note that the conversion does not take the current locale into consideration, which might be expected for particular keyvals, such as GDK_KEY_KP_Decimal.
See also:
2024-7-9
Function gdk:unicode-to-keyval (unicode)
Arguments:
unicode -- an unsigned integer with a ISO10646 encoded character
Returns:
The unsigned integer with the corresponding GDK key value, if one exists, or, if there is no corresponding symbol, wc | 0x01000000
Details:
Convert from a ISO10646 character to a GDK key value.
See also:
2024-7-9

GdkDmabufFormats

GBoxed gdk:dmabuf-formats
Declaration:
(glib:define-gboxed-opaque dmabuf-formats "GdkDmabufFormats"
  :export t
  :type-initializer "gdk_dmabuf_formats_get_type"
  :alloc (error "GdkDmabufFormats cannot be created from the Lisp side"))  
Details:
The gdk:dmabuf-formats structure provides information about supported DMA buffer formats. You can query whether a given format is supported with the gdk:dmabuf-formats-contains function and you can iterate over the list of all supported formats with the gdk:dmabuf-formats-n-formats and gdk:dmabuf-formats-format function.

The list of supported formats is sorted by preference, with the best formats coming first. The list may contain (format, modifier) pairs where the modifier is DMA_FORMAT_MOD_INVALID, indicating that implicit modifiers may be used with this format.

See the gdk:dmabuf-texture-builder documentation for more information about DMA buffers. Note that DMA buffers only exist on Linux.

Since 4.14
See also:
2024-5-26
Function gdk:dmabuf-formats-contains (formats fourcc modifier)
Arguments:
formats -- a gdk:dmabuf-formats instance
fourcc -- an integer with the format code
modifier -- an integer with the format modifier
Returns:
True if the format specified by the arguments is part of formats.
Details:
Returns whether a given format is contained in formats.

Since 4.14
See also:
2024-7-10
Function gdk:dmabuf-formats-equal (formats1 formats2)
Arguments:
formats1 -- a gdk:dmabuf-formats instance
formats2 -- another gdk:dmabuf-formats instance
Returns:
True if formats1 and formats2 are equal.
Details:
Returns whether formats1 and formats2 contain the same dmabuf formats, in the same order.

Since 4.14
See also:
2024-7-10
Function gdk:dmabuf-formats-format (formats idx)
Arguments:
formats -- a gdk:dmabuf-formats instance
idx -- an integer with the index of the format to return
Returns:
fourcc -- an integer with the format code
modifier -- an integer with the format modifier
Details:
Gets the fourcc code and modifier for a format that is contained in formats.

Since 4.14
See also:
2024-7-10
Function gdk:dmabuf-formats-n-formats (formats)
Arguments:
formats -- a gdk:dmabuf-formats instance
Returns:
The integer with the number for formats.
Details:
Returns the number of formats that the formats object contains. Note that DMA buffers are a Linux concept, so on other platforms, the gdk:dmabuf-formats-n-formats function will always return zero.

Since 4.14
See also:
2024-7-10

GdkColorState

GBoxed gdk:color-state
Declaration:
(glib:define-gboxed-opaque color-state "GdkColorState"
  :export t
  :type-initializer "gdk_color_state_get_type"
  :alloc (error "GdkColorState cannot be created from the Lisp side"))  
Details:
The gdk:color-state structure provides the information to interpret colors and pixels in a variety of ways. They are also known as color spaces.

Crucially, GTK knows how to convert colors from one color state to another. The gdk:color-state instances are immutable and therefore threadsafe.

Since 4.16
See also:
2024-11-28
Function gdk:color-state-rec2100-linear ()
Returns:
The gdk:color-state instance for linearized rec2100.
Details:
Returns the color state object representing the linear rec2100 color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear transfer function. It is equivalent to the Cicp tuple 9/8/0/1. See for example the CSS HDR Module for details about this colorstate.

Since 4.16
See also:
2024-11-10
Function gdk:color-state-rec2100-pq ()
Returns:
The gdk:color-state instance for rec2100-pq.
Details:
Returns the color state object representing the rec2100-pq color space. This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer function defined by SMPTE ST 2084 and BT.2100-2. It is equivalent to the Cicp tuple 9/16/0/1. See for example the CSS HDR Module for details about this colorstate.

Since 4.16
See also:
2024-11-10
Function gdk:color-state-srgb ()
Returns:
The gdk:color-state instance for sRGB.
Details:
Returns the color state object representing the sRGB color space. This color state uses the primaries defined by BT.709-6 and the transfer function defined by IEC 61966-2-1. It is equivalent to the Cicp tuple 1/13/0/1. See for example the CSS HDR Module for details about this colorstate.

Since 4.16
See also:
2024-11-10
Function gdk:color-state-srgb-linear ()
Returns:
The gdk:color-state instance for linearized sRGB.
Details:
Returns the color state object representing the linearized sRGB color space. This color state uses the primaries defined by BT.709-6 and a linear transfer function. It is equivalent to the Cicp tuple 1/8/0/1. See for example the CSS HDR Module for details about this colorstate.

Since 4.16
See also:
2024-11-10
Function gdk:color-state-create-cicp-params (color)
Arguments:
color -- a gdk:color-state instance
Returns:
The new gdk:cicp-params object.
Details:
Create a gdk:cicp-params object representing the colorstate. It is not guaranteed that every gdk:color-state instance can be represented with Cicp parameters. If that is the case, this function returns nil.

Since 4.16
See also:
2024-11-10
Function gdk:color-state-equal (color1 color2)
Arguments:
color1 -- a gdk:color-state instance
color2 -- another gdk:color-state instance
Details:
Compares two color states for equality. Note that this function is not guaranteed to be perfect and two objects describing the same color state may compare not equal. However, different color states will never compare equal.

Since 4.16
See also:
2024-11-10

GdkCicpParams

GEnum gdk:cicp-range
Declaration:
(gobject:define-genum "GdkCicpRange" cicp-range
  (:export t
   :type-initializer "gdk_cicp_range_get_type")
  :narrow
  :full)  
Values:
:narrow
The values use the range of 16-235 (for Y) and 16-240 for u and v.
:full
The values use the full range.
Details:
The values of this enumeration describe whether image data uses the full range of 8-bit values.

In digital broadcasting, it is common to reserve the lowest and highest values. Typically the allowed values for the narrow range are 16-235 for Y and 16-240 for u,v (when dealing with YUV data).

Since 4.16
See also:
2024-11-10
Class gdk:cicp-params
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
color-primaries
The color-primaries property of type :uint (Read / Write)
The color primaries to use.
Default value: 2
matrix-coefficients
The matrix-coefficients property of type :uint (Read / Write)
The matrix coefficients (for YUV to RGB conversion).
Default value: 2
range
The range property of type gdk:cicp-range (Read / Write)
Whether the data is using the full range of values.
Default value: :narrow
transfer-function
The transfer-function property of type :uint (Read / Write)
The transfer function to use.
Default value: 2
Returned by:
Slot Access Functions:
Details:
The gdk:cicp-params object contains the parameters that define a colorstate according to the ITU-T H.273 specification. See the documentation of individual properties for supported values.

The 'unspecified' value (2) is not treated in any special way, and must be replaced by a different value before creating a color state.

The gdk:cicp-params object can be used as a builder object to construct a color state from Cicp data with the gdk:cicp-params-build-color-state function. The function will return an error if the given parameters are not supported.

You can obtain a gdk:cicp-params object from a color state with the gdk:color-state-create-cicp-params function. This can be used to create a variant of a color state, by changing just one of the Cicp parameters, or just to obtain information about the color state.

Since 4.16
See also:
2024-11-10
Accessor gdk:cicp-params-color-primaries (object)
Syntax:
(gdk:cicp-params-color-primaries object) => primaries
(setf (gdk:cicp-params-color-primaries object) primaries)
Arguments:
object -- a gdk:cicp-params object
primaries -- an unsigned integer with the color primaries value
Details:
Accessor of the color-primaries slot of the gdk:cicp-params class. The gdk:cicp-params-color-primaries function returns the color primaries value. The (setf gdk:cicp-params-color-primaries) function sets the value.

Supported values are:
  • 1: BT.709 / sRGB
  • 2: unspecified
  • 5: PAL
  • 6,7: BT.601 / NTSC
  • 9: BT.2020
  • 12: Display P3
Since 4.16
See also:
#2024-11-10
Accessor gdk:cicp-params-matrix-coefficients (object)
Syntax:
(gdk:cicp-params-matrix-coefficients object) => coefficients
(setf (gdk:cicp-params-matrix-coefficients object) coefficients)
Arguments:
object -- a gdk:cicp-params object
coefficients -- an unsigned integer with the matrix coefficients value
Details:
Accessor of the matrix-coefficients slot of the gdk:cicp-params class. The gdk:cicp-params-matrix-coefficients function gets the matrix coefficients of object. The (setf gdk:cicp-params-matrix-coefficients) function sets the matrix coefficients.

Supported values are:
  • 0: RGB
  • 2: unspecified
Since 4.16
See also:
#2024-11-10
Accessor gdk:cicp-params-range (object)
Syntax:
(gdk:cicp-params-range object) => range
(setf (gdk:cicp-params-range object) range)
Arguments:
object -- a gdk:cicp-params object
range -- a gdk:cicp-range value
Details:
Accessor of the range slot of the gdk:cicp-params class. The gdk:cicp-params-range function gets the range value of object. The (setf gdk:cicp-params-range) function sets the range value.
See also:
#2024-11-10
Accessor gdk:cicp-params-transfer-function (object)
Syntax:
(gdk:cicp-params-transfer-function object) => function
(setf (gdk:cicp-params-transfer-function object) function)
Arguments:
object -- a gdk:cicp-params object
function -- an unsigned integer with the transfer function value
Details:
Accessor of the transfer-function slot of the gdk:cicp-params class. The gdk:cicp-params-transfer-function function gets the transfer function value of object. The (setf gdk:cicp-params-transfer-function) function sets the transfer function value.

Supported values are:
  • 1,6,14,15: BT.709, BT.601, BT.2020
  • 2: unspecified
  • 4: gamma 2.2
  • 5: gamma 2.8
  • 8: linear
  • 13: sRGB
  • 16: BT.2100 PQ
  • 18: BT.2100 HLG
Since 4.16
See also:
#2024-11-10
Function gdk:cicp-params-new ()
Returns:
The new gdk:cicp-params object.
Details:
Creates a new gdk:cicp-params object. The initial values of the properties are the values for 'undefined' and need to be set before a color state object can be built.

Since 4.16
See also:
#2024-11-10
Function gdk:cicp-params-build-color-state (params)
Arguments:
params -- a gdk:cicp-params object
Returns:
The newly allocated gdk:color-state instance.
Details:
Creates a new gdk:color-state object for the Cicp parameters in params. Note that this may fail if the Cicp parameters in params are not supported by GTK. In that case, nil is returned.

Since 4.16
See also:
#2024-11-10

Displays, Devices, Monitors, and Seats

GdkDisplayManager

Class gdk:display-manager
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
default-display
The default-display property of type gdk:display (Read / Write)
The default display for GDK.
Slot Access Functions:
Details:
The purpose of the gdk:display-manager singleton object is to offer notification when displays appear or disappear or the default display changes. You can use the gdk:display-manager-get function to obtain the gdk:display-manager singleton, but that should be rarely necessary. Typically, initializing GTK opens a display that you can work with without ever accessing the gdk:display-manager object.

The GDK library can be built with support for multiple backends. The gdk:display-manager object determines which backend is used at runtime.
Signal Details:
The "display-opened" signal
lambda (manager display)    :run-last      
manager
The gdk:display-manager object on which the signal is emitted.
display
The opened gdk:display object.
The signal is emitted when a display is opened.
See also:
2024-7-10
Accessor gdk:display-manager-default-display (object)
Syntax:
(gdk:display-manager-default-display object) => display
(setf (gdk:display-manager-default-display object) display)
Arguments:
object -- a gdk:display-manager object
display -- a default gdk:display object
Details:
Accessor of the default-display slot of the gdk:display-manager class. The gdk:display-manager-default-display function gets the default gdk:display object, or nil if there is no default display. The (setf gdk:display-manager-default-display) function sets display as the default display.
Examples:
(gdk:display-manager-default-display (gdk:display-manager-get))
=> #<GDK:DISPLAY {1001F9A233}>    
See also:
2024-7-10
Function gdk:display-manager-get ()
Returns:
The global gdk:display-manager singleton object.
Details:
Gets the gdk:display-manager singleton 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.
Examples:
(gdk:display-manager-get)
=> #<GDK:DISPLAY-MANAGER {1001CFF103}>    
See also:
2024-7-10
Function gdk:display-manager-list-displays (manager)
Arguments:
manager -- a gdk:display-manager object
Returns:
The list of gdk:display objects.
Details:
List all currently open displays.
See also:
2024-7-10
Function gdk:display-manager-open-display (manager name)
Arguments:
manager -- a gdk:display-manager object
name -- a string with the name of the display to open
Returns:
The gdk:display object, or nil if the display could not be opened.
Details:
Opens a display.
See also:
2024-7-10
Function gdk:set-allowed-backends (backends)
Arguments:
backends -- a string with a comma-separated list of backends
Details:
Sets a list of backends that GDK should try to use. This can be useful if your application does not work with certain GDK backends. By default, GDK tries all included backends. For example,
(gdk:set-allowed-backends "wayland,quartz,*")  
instructs GDK to try the Wayland backend first, followed by the Quartz backend, and then all others.

If the GDK_BACKEND environment variable is set, it determines what backends are tried in what order, while still respecting the set of allowed backends that are specified by this function.

The possible backend names are x11, win32, quartz, broadway, wayland. You can also include a * in the list to try all remaining backends.

This call must happen prior to the gdk:display-open, gtk:init, or gtk:init-check functions in order to take effect.
See also:
#2024-7-10

GdkDisplay

Class gdk:display
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
composited
The composited property of type :boolean (Read)
True if the display properly composites the alpha channel.
dmabuf-formats
The dmabuf-formats property of type gdk:dmabuf-formats (Read)
The DmaBuf formats that are supported on the display. Since 4.14
input-shapes
The input-shapes property of type :boolean (Read)
True if the display supports input shapes.
rgba
The rgba property of type :boolean (Read)
True if the display supports an alpha channel.
shadow-width
The shadow-width property of type :boolean (Read)
True if the display supports extensible frames. Since 4.14
Slot Access Functions:
Details:
The gdk:display object is the GDK representation of a workstation. The purpose is two fold:
  • To manage and provide information about input devices, for example, pointers and keyboards.
  • To manage and provide information about output devices, for example, monitors and projectors.
Most of the input device handling has been factored out into separate gdk:seat objects. Every display has one or more seats, which can be accessed with the gdk:display-default-seat and gdk:display-list-seats functions.

Output devices are represented by gdk:monitor objects, which can be accessed with the gdk:display-monitor-at-surface function and similar APIs.
Signal Details:
The "closed" signal
lambda (display is-error)    :run-last      
display
The gdk:display object on which the signal is emitted.
is-error
The boolean that is true if display was closed due to an error.
Emitted when the connection to the windowing system for display is closed.
The "opened" signal
lambda (display)   :run-last      
display
The gdk:display object on which the signal is emitted.
Emitted when the connection to the windowing system for display is opened.
The "seat-added" signal
lambda (display seat)    :run-last      
display
The gdk:display object on which the signal is emitted.
seat
The gdk:seat object that was just added.
Emitted whenever a new seat is made known to the windowing system.
The "seat-removed" signal
lambda (display seat)    :run-last      
display
The gdk:display object on which the signal is emitted.
seat
The gdk:seat object that was just removed.
Emitted whenever a seat is removed by the windowing system.
The "setting-changed" signal
lambda (display setting)    :run-last    
display
The gdk:display object on which the signal is emitted.
setting
The string with the name of the setting that changed.
See also:
2024-5-25
Accessor gdk:display-composited (object)
Syntax:
(gdk:display-composited object) => composited
Arguments:
object -- a gdk:display object
composited -- true if the display properly composites the alpha channel
Details:
Accessor of the composited slot of the gdk:display class. The gdk:display-composited function returns whether surfaces can reasonably be expected to have their alpha channel drawn correctly on the screen. Check with the gdk:display-is-rgba function for whether the display supports an alpha channel.

On X11 this function returns whether a compositing manager is compositing on display. On modern displays, this value is always true.
See also:
2024-1-7
Accessor gdk:display-dmabuf-formats (object)
Syntax:
(gdk:display-dmabuf-formats object) => formats
Arguments:
object -- a gdk:display object
formats -- a gdk:dmabuf-formats instance
Details:
Returns the dma-buf formats that are supported on the display. GTK may use OpenGL or Vulkan to support some formats. Calling this function will then initialize them if they are not yet.

The formats returned by this function can be used for negotiating buffer formats with producers such as v4l, pipewire or GStreamer. To learn more about dma-buf formats, see the gdk:dmabuf-texture-builder documentation.

Since 4.14
See also:
2024-11-5
Accessor gdk:display-input-shapes (object)
Syntax:
(gdk:display-input-shapes object) => setting
Arguments:
object -- a gdk:display object
setting -- true if the display supports input shapes
Details:
Accessor of the input-shapes slot of the gdk:display class. The gdk:display-input-shapes function returns true if the display supports input shapes. This means that the gdk:surface-set-input-region function can be used to modify the input shape of surfaces on the display.

On modern displays, this value is always true.
See also:
2024-1-7
Accessor gdk:display-rgba (object)
Syntax:
(gdk:display-rgba object) => setting
Arguments:
object -- a gdk:display object
setting -- true if the display supports an alpha channel
Details:
Accessor of the rgba slot of the gdk:display class. The gdk:display-rgba function returns whether surfaces on the display are created with an alpha channel.

Even if a true is returned, it is possible that the alpha channel of the surface will not be honored when displaying the surface on the screen. In particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. Use the gdk:display-is-composited function to check if that is the case.

On modern displays, this value is always true.
See also:
2024-1-7
Accessor gdk:display-shadow-width (object)
Syntax:
(gdk:display-shadow-width object) => setting
Arguments:
object -- a gdk:display object
setting -- true if surfaces can draw shadows or false if the display does not support this functionality
Details:
Returns whether it is possible for a surface to draw outside of the window area. If true is returned the application decides if it wants to draw shadows. If false is returned, the compositor decides if it wants to draw shadows.

Since 4.14
See also:
2024-5-26
Function gdk:display-open (name)
Arguments:
name -- a string with the name of the display to open
Returns:
The gdk:display object, or nil if the display could not be opened.
Details:
Opens a display named by name. If opening the display fails, nil is returned.
See also:
2024-7-11
Function gdk:display-default ()
Returns:
The gdk:display object, or nil if there is no default display.
Details:
Gets the default display. This is a convenience function for the call:
(gdk:display-manager-default-display (gdk:display-manager-get))  
Examples:
(gdk:display-default)
=> #<GDK:DISPLAY {1007501013}>
(eq (gdk:display-default)
    (gdk:display-manager-default-display (gdk:display-manager-get)))
=> T    
See also:
2024-9-29
Function gdk:display-name (display)
Arguments:
display -- a gdk:display object
Returns:
The string representing the display name.
Details:
Gets the name of the display.
See also:
2024-1-7
Function gdk:display-device-is-grabbed (display device)
Arguments:
display -- a gdk:display object
device -- a gdk:device object
Returns:
The boolean that is true if there is a grab in effect for device.
Details:
Returns true if there is an ongoing grab on the device for the display.
See also:
2024-1-7
Function gdk:display-beep (display)
Arguments:
display -- a gdk:display object
Details:
Emits a short beep on the display.
See also:
2024-1-7
Function gdk:display-sync (display)
Arguments:
display -- a gdk:display object
Details:
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 the gdk:display-sync function before the gdk_x11_display_error_trap_pop() function 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.
See also:
2024-1-7
Function gdk:display-flush (display)
Arguments:
display -- a gdk:display object
Details:
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 explicitely. 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.
See also:
2024-1-7
Function gdk:display-close (display)
Arguments:
display -- a gdk:display object
Details:
Closes the connection to the windowing system for the given display. This cleans up associated resources.
See also:
#2024-11-5
Function gdk:display-is-closed (display)
Arguments:
display -- a gdk:display object
Returns:
True if display is closed.
Details:
Finds out if the display has been closed.
See also:
2024-7-11
Function gdk:display-is-rgba (display)
Arguments:
display -- a gdk:display object
Returns:
True if the display supports an alpha channel.
Details:
Returns whether surfaces on this display are created with an alpha channel.

Even if a true value is returned, it is possible that the alpha channel of the surface will not be honored when displaying the surface on the screen. In particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. Use the gdk:display-is-composited function to check if that is the case. On modern displays, this value is always true.
See also:
2024-1-7
Function gdk:display-is-composited (display)
Arguments:
display -- a gdk:display object
Returns:
Whether surfaces with RGBA visuals supports an alpha channel.
Details:
Returns whether surfaces can reasonably be expected to have their alpha channel drawn correctly on the screen.

Check the value of the gdk:display-is-rgba function for whether the display supports an alpha channel. On X11 this function returns whether a compositing manager is compositing on display. On modern displays, this value is always true.
See also:
2024-1-7
Function gdk:display-supports-input-shapes (display)
Arguments:
display -- a gdk:display object
Returns:
True if surfaces with modified input shape are supported.
Details:
Returns true if the display supports input shapes. This means that the gdk:surface-set-input-region function can be used to modify the input shape of surfaces on the display. On modern displays, this value is always true.
See also:
2024-1-7
Function gdk:display-app-launch-context (display)
Arguments:
display -- a gdk:display object
Returns:
The new gdk:app-launch-context object for display.
Details:
Returns a gdk:app-launch-context object suitable for launching applications on the given display.
See also:
2025-1-1
Function gdk:display-notify-startup-complete (display startup)
Arguments:
display -- a gdk:display object
startup -- a string with a startup notification identifier, for which notification process should be completed
Details:
Indicates to the GUI environment that the application has finished loading, using a given identifier. GTK will call this function automatically for gtk:window widgets with a custom startup notification identifier unless the gtk:window-set-auto-startup-notification function is called to disable that feature.
Warning:
The gdk:display-notify-startup-complete function is deprecated since 4.10. Using the gdk:toplevel-startup-id function is sufficient.
See also:
#2024-1-7
Function gdk:display-default-seat (display)
Arguments:
display -- a gdk:display object
Returns:
The default gdk:seat object.
Details:
Returns the default seat object for this display. Note that a display may not have a seat. In this case, this function will return nil.
See also:
2024-1-7
Function gdk:display-list-seats (display)
Arguments:
display -- a gdk:display object
Returns:
The list of gdk:seat objects known to display.
Details:
Returns the list of seats known to the display.
See also:
2025-1-11
Function gdk:display-monitors (display)
Arguments:
display -- a gdk:display object
Returns:
The Lisp list of gdk:monitor objects.
Details:
Gets the list of monitors associated with the display. Subsequent calls to this function will always return the same list for the same display.
Lisp implementation:
The C code returns a g:list-model instance with pointers to the monitors. For the Lisp implementation, the list is converted to a Lisp list with gdk:monitor objects.
See also:
2024-1-7
Function gdk:display-monitor-at-surface (display surface)
Arguments:
display -- a gdk:display object
surface -- a gdk:surface object
Returns:
The gdk:monitor object with the largest overlap with surface.
Details:
Gets the monitor in which the largest area of the surface resides. Returns a monitor close to surface if it is outside of all monitors.
See also:
#2024-1-7
Function gdk:display-clipboard (display)
Arguments:
display -- a gdk:display object
Returns:
The gdk:clipboard object.
Details:
Gets the clipboard used for copy/paste operations.
See also:
2024-1-7
Function gdk:display-primary-clipboard (display)
Arguments:
display -- a gdk:display object
Returns:
The gdk:clipboard object.
Details:
Gets the clipboard used for the primary selection. On backends where the primary clipboard is not supported natively, GDK emulates this clipboard locally.
See also:
2024-1-7
Function gdk:display-setting (display name gtype)
Arguments:
display -- a gdk:display object
name -- a string with the name of the setting
gtype -- a g:type-t type ID with the type of the setting
Returns:
The value of the setting or nil if the setting does not exist.
Details:
Retrieves a desktop-wide setting such as double-click time for the display.
Examples:
(let ((display (gdk:display-default)))
  (gdk:display-setting display "gtk-double-click-time" "gint"))
=> 400    
See also:
2024-1-7
Function gdk:display-startup-notification-id (display)
Arguments:
display -- a gdk:display object
Returns:
The string with the startup notification ID for display.
Details:
Gets the startup notification ID for a Wayland display, or nil if no ID has been defined.
Warning:
The gdk:display-startup-notification-id function is deprecated since 4.10. Do not use it in newly written code.
See also:
2024-1-7
Function gdk:display-map-keyval (display keyval)
Arguments:
display -- a gdk:display object
keyval -- an unsigned integer with the keyval
Returns:
The list of integer with the grouped keycode/group/level combinations, or nil.
Details:
Obtains a list of keycode/group/level combinations that will generate keyval. Groups and levels are two kinds of keyboard mode. In general, the level determines whether the top or bottom symbol on a key is used, and the group determines whether the left or right symbol is used.

On US keyboards, the shift key changes the keyboard level, and there are no groups. A group switch key might convert a keyboard between Hebrew to English modes, for example.
Examples:
(gdk:display-map-keyval (gdk:display-default) (char-code #a))
=> ((65 0 0) (65 0 3) (65 0 15) (65 0 2))    
See also:
2024-1-7
Function gdk:display-map-keycode (display keycode)
Arguments:
display -- a gdk:display object
keycode -- an unsigned integer with a keycode
Returns:
The list of keyvals with the corresponding key of the form (keyval keycode group level).
Details:
Returns the keyvals bound to keycode. When a keycode is pressed by the user, the keyval from this list of entries is selected by considering the effective keyboard group and level.
See also:
2024-1-7
Function gdk:display-translate-key (display keycode state group)
Arguments:
display -- a gdk:display object
keycode -- an unsigned integer for the keycode
state -- a gdk:modifier-type state
group -- an integer for the active keyboard group
Returns:
keyval - an unsigned integer with the keyval
effective - an integer with the effective group
level - an integer with the level
consumend - a gdk:modifier-type value with the modifiers that were used to determine the group or level
Details:
Translates a keycode into a keyval, effective group, and level. Modifiers that affected the translation and are thus unavailable for application use are returned in consumed.

The effective value is the group that was actually used for the translation. Some keys such as Enter are not affected by the active keyboard group. The level value is derived from state.

The consumed value gives modifiers that should be masked out from state when comparing this key press to a keyboard shortcut. For instance, on a US keyboard, the plus symbol is shifted, so when comparing a key press to a <Control>plus accelerator <Shift> should be masked out.
See also:
2025-1-11
Function gdk:display-prepare-gl (display)
Arguments:
display -- a gdk:display object
Returns:
True if the display supports OpenGL.
Details:
Checks that OpenGL is available for display and ensures that it is properly initialized. When this fails, an error will be set describing the error and this function returns false.

Note that even if this function succeeds, creating a gdk:gl-context object may still fail. This function is idempotent. Calling it multiple times will just return the same value or error.

You never need to call this function, GDK will call it automatically as needed. But you can use it as a check when setting up code that might make use of OpenGL.

Since 4.4
See also:
#2024-11-21
Function gdk:display-create-gl-context (display)
Arguments:
display -- a gdk:display object
Returns:
The newly created gdk:gl-context object.
Details:
Creates a new OpenGL context for the display. The context is disconnected from any particular surface and cannot be used to draw to any surface. It can only be used to draw to non-surface framebuffers like textures.

If the creation of the OpenGL context failed, an error will be set. Before using the returned OpenGL context, you will need to call the gdk:gl-context-make-current or gdk:gl-context-realize functions.

Since 4.6
See also:
#2024-11-21

GdkDeviceTool

GEnum gdk:device-tool-type
Declaration:
(gobject:define-genum "GdkDeviceToolType" device-tool-type
  (:export t
   :type-initializer "gdk_device_tool_type_get_type")
  :unknown
  :pen
  :eraser
  :brush
  :pencil
  :airbrush
  :mouse
  :lens)  
Values:
:unkown
Tool is of an unknown type.
:pen
Tool is a standard tablet stylus.
:eraser
Tool is standard tablet eraser.
:brush
Tool is a brush stylus.
:pencil
Tool is a pencil stylus.
:airbrush
Tool is an airbrush stylus.
:mouse
Tool is a mouse.
:lens
Tool is a lens cursor.
Details:
Indicates the specific type of tool being used being a tablet. Such as an airbrush, pencil, etc.
See also:
2024-7-11
Class gdk:device-tool
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
axes
The axes property of type gdk:axis-flags (Read / Write / Construct Only)
The device tool axes.
hardware-id
The hardware-id property of type :uint64 (Read / Write / Construct Only)
The hardware ID.
Default value: 0
serial
The serial property of type :uint64 (Read / Write / Construct Only)
The serial number.
Default value: 0
tool-type
The tool-type property of type gdk:device-tool-type (Read / Write / Construct Only)
The tool type.
Default value: :unknown
Slot Access Functions:
Details:
A physical tool associated to a gdk:device object.
See also:
2024-1-7
Accessor gdk:device-tool-axes (object)
Syntax:
(gdk:device-tool-axes object) => axes
Arguments:
object -- a gdk:device-tool object
axes -- a gdk:axis-flags value
Details:
Accessor of the axes slot of the gdk:device-tool class. The gdk:device-tool-axes function gets the axes of the device tool.
See also:
2024-1-7
Accessor gdk:device-tool-hardware-id (object)
Syntax:
(gdk:device-tool-hardware-id object) => hardware-id
Arguments:
object -- a gdk:device-tool object
hardware-id -- an unsigned integer with the hardware identificator of the device tool
Details:
Accessor of the hardware-id slot of the gdk:device-tool class. The gdk:device-tool-hardware-id function gets the hardware ID of the device tool, or 0 if it is 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 the gdk:device-tool-serial function.

This is a more concrete and device specific method to identify a device tool than the gdk:device-tool-tool-type function, as a tablet may support multiple devices with the same gdk:device-tool-type value, but having different hardware identificators.
See also:
2024-1-7
Accessor gdk:device-tool-serial (object)
Syntax:
(gdk:device-tool-serial object) => serial
Arguments:
object -- a gdk:device-tool object
serial -- an unsigned integer with the serial ID for the device tool
Details:
Accessor of the serial slot of the gdk:device-tool class. The gdk:device-tool-serial function gets the serial of the device tool, the value can be used to identify a physical tool, for example, a tablet pen, across program executions.
See also:
2024-1-7
Accessor gdk:device-tool-tool-type (object)
Syntax:
(gdk:device-tool-tool-type object) => tool-type
Arguments:
object -- a gdk:device-tool object
tool-type -- a gdk:device-tool-type value
Details:
Accessor of the tool-type slot of the gdk:device-tool class. The gdk:device-tool-tool-type function gets the gdk:device-tool-type value of the device tool. This can be used to figure out what sort of pen is being used, such as an airbrush or a pencil.
See also:
2024-1-7

GdkDevice

GEnum gdk:input-source
Declaration:
(gobject:define-genum "GdkInputSource" input-source
  (:export t
   :type-initializer "gdk_input_source_get_type")
  :mouse
  :pen
  :keyboard
  :touchscreen
  :touchpad
  :trackpoint
  :tablet-pad)  
Values:
:mouse
The device is a mouse. This will be reported for the core pointer, even if it is something else, such as a trackball.
:pen
The device is a stylus of a graphics tablet or similar device.
:keyboard
The device is a keyboard.
:touchscreen
The device is a direct-input touch device, such as a touchscreen or tablet.
:touchpad
The device is an indirect touch device, such as a touchpad.
:trackpoint
The device is a trackpoint.
:tablet-pad
The device is a "pad", a collection of buttons, rings and strips found in drawing tablets.
Details:
An enumeration describing the type of an input device in general terms.
See also:
2024-7-12
GEnum gdk:axis-use
Declaration:
(gobject:define-genum "GdkAxisUse" gdk-axis-use
  (:export t
   :type-initializer "gdk_axis_use_get_type")
  :ignore
  :x
  :y
  :delta-x
  :delty-y
  :pressure
  :xtilt
  :ytilt
  :wheel
  :distance
  :rotation
  :slider
  :last)  
Values:
:ignore
The axis is ignored.
:x
The axis is used as the x axis.
:y
The axis is used as the y axis.
:delta-x
The axis is used as the scroll x delta.
:delta-y
The axis is used as the scroll y delta.
:pressure
The axis is used for pressure information.
:xtilt
The axis is used for x tilt information.
:ytilt
The axis is used for y tilt information.
:wheel
The axis is used for wheel information.
:distance
The axis is used for pen/tablet distance information.
:rotation
The axis is used for pen rotation information.
:slider
The axis is used for pen slider information.
:last
The constant equal to the numerically highest axis value.
Details:
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.
See also:
2024-7-12
GFlags gdk:axis-flags
Declaration:
(gobject:define-gflags "GdkAxisFlags" axis-flags
  (:export t
   :type-initializer "gdk_axis_flags_get_type")
  (:x        #.(ash 1 1))
  (:y        #.(ash 1 2))
  (:delta-x  #.(ash 1 3))
  (:delta-y  #.(ash 1 4))
  (:pressure #.(ash 1 5))
  (:xtilt    #.(ash 1 6))
  (:ytilt    #.(ash 1 7))
  (:wheel    #.(ash 1 8))
  (:distance #.(ash 1 9))
  (:rotation #.(ash 1 10))
  (:slider   #.(ash 1 11)))  
Values:
:x
x axis is present.
:y
y axis is present.
:delta-x
Scroll X delta axis is present.
:delta-y
Scroll Y delta axis is present
:pressure
Pressure axis is present.
:xtilt
x tilt axis is present.
:ytilt
y tilt axis is present.
:wheel
Wheel axis is present.
:distance
Distance axis is present.
:rotation
z-axis rotation is present.
:slider
Slider axis is present.
Details:
Flags describing the current capabilities of a device/tool.
See also:
2024-7-12
Class gdk:device
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
caps-lock-state
The caps-lock-state property of type :boolean (Read)
Whether the keyboard caps lock is on.
Default value: false
direction
The direction property of type pango:direction (Read)
The direction of the current layout of the keyboard.
Default value: :neutral
display
The display property of type gdk:display (Read / Write / Construct Only)
The display the device pertains to.
has-bidi-layouts
The has-bidi-layouts property of type :boolean (Read)
Whether the keyboard has bidi layouts.
Default value: false
has-cursor
The cursor property of type :boolean (Read / Write / Contstruct Only)
Whether the device is represented by a cursor on the screen.
Default value: false
modifier-state
The modifier-state property of type gdk:modifier-type (Read)
The modifier state of the keyboard.
n-axes
The n-axes property of type :uint (Read)
The number of axes in the device.
Default value: 0
name
The name property of type :string (Read / Write / Construct Only)
The device name.
Default value: nil
num-lock-state
The num-lock-state property of type :boolean (Read)
Whether the keyboard num lock is on.
Default value: false
num-touches
The num-touches property of type :uint (Read / Write / Construct Only)
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.
Default value: 0
product-id
The product-id property of type :string (Read / Write / Construct Only)
The product ID of the device.
Default value: nil
scroll-lock-state
The scroll-lock-state property of type :boolean (Read)
Whether the keyboard scroll lock is on.
Default value: false
seat
The seat property of type gdk:seat (Read / Write)
The seat of the device.
source
The source property of type gdk:input-source (Read / Write / Construct Only)
The source type of the device.
Default value: :mouse
tool
The tool property of type gdk:device-tool (Read)
The tool that is currently used with the device.
vendor-id
The vendor-id property of type :string (Read / Write / Construct Only)
The vendor ID of this device.
Default value: nil
Slot Access Functions:
Details:
The gdk:device object represents a single input device, such as a keyboard, a mouse, a touchpad, etc. See the gdk:seat documentation for more information about the various kinds of devices, and their relationships.
Signal Details:
The "changed" signal
lambda (device)    :run-last      
device
The gdk:device object that changed.
The signal is emitted either when the gdk:device object has changed the number of either axes or keys. For example In X this will normally happen when the physical device routing events through the logical device changes, for example, user switches from the USB mouse to a tablet, in that case the logical device will change to reflect the axes and keys on the new physical device.
The "tool-changed" signal
lambda (device tool)    :run-last      
device
The gdk:device object that changed.
tool
The new gdk:device-tool current device tool.
The signal is emitted on pen/eraser devices whenever tools enter or leave proximity.
See also:
2024-7-12
device-active-layout-index
Accessor gdk:device-caps-lock-state (object)
Syntax:
(gdk:device-caps-lock-state object) => setting
Arguments:
object -- a gdk:device object
setting -- a boolean whether the keyboard caps lock is on
Details:
Accessor of the caps-lock-state slot of the gdk:device class. The gdk:device-caps-lock-state function retrieves whether the Caps Lock modifier of the keyboard is locked, if object is a keyboard device.
See also:
2024-1-7
Accessor gdk:device-direction (object)
Syntax:
(gdk:device-direction object) => direction
Arguments:
object -- a gdk:device object
direction -- a pango:direction value
Details:
Accessor of the direction slot of the gdk:device class. The gdk:device-direction function returns the direction of the effective layout of the keyboard, if object is a keyboard device. The direction of a layout is the direction of the majority of its symbols.
See also:
2024-7-12
Accessor gdk:device-display (object)
Syntax:
(gdk:device-display object) => display
Arguments:
object -- a gdk:device object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:device class. The gdk:device-display function returns the display to which the device pertains.
See also:
2024-1-7
Accessor gdk:device-has-bidi-layouts (object)
Syntax:
(gdk:device-has-bidi-layouts object) => setting
Arguments:
object -- a gdk:device object
setting -- true if there are layouts with both directions, false otherwise
Details:
Accessor of the has-bidi-layouts slot of the gdk:device class. The gdk:device-has-bidi-layouts function determines if keyboard layouts for both right-to-left and left-to-right languages are in use on the keyboard, if object is a keyboard device.
See also:
2024-1-7
Accessor gdk:device-has-cursor (object)
Syntax:
(gdk:device-has-cursor object) => setting
Arguments:
object -- a gdk:device object
setting -- true if the pointer follows device motion
Details:
Accessor of the has-cursor slot of the gdk:device class. The gdk:device-has-cursor function determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which do not have a pointer.
See also:
2024-1-7
Accessor gdk:device-modifier-state (object)
Syntax:
(gdk:device-modifier-state object) => state
Arguments:
object -- a gdk:device object
state -- a gdk:modifier-type value with the current modifier state
Details:
Accessor of the modifier-state slot of the gdk:device class. The gdk:device-modifier-state function retrieves the current modifier state of the keyboard, if object is a keyboard device.
See also:
2024-7-12
Accessor gdk:device-n-axes (object)
Syntax:
(gdk:device-n-axes object) => n-axes
Arguments:
object -- a gdk:device object
n-axes -- an unsigned integer with the number of axes in the device
Details:
Accessor of the n-axes slot of the gdk:device class. The gdk:device-n-axes function gets the number of axes in the device.
See also:
2024-1-7
Accessor gdk:device-name (object)
Syntax:
(gdk:device-name object) => name
Arguments:
object -- a gdk:device object
name -- a string with the name of the device
Details:
Accessor of the name slot of the gdk:device class. The gdk:device-name function determines the name of the device, suitable for showing in a user interface.
See also:
2024-1-7
Accessor gdk:device-num-lock-state (object)
Syntax:
(gdk:device-num-lock-state object) => setting
Arguments:
object -- a gdk:device object
setting -- true if Num Lock is on for the device
Details:
Accessor of the num-lock-state slot of the gdk:device class. The gdk:device-num-lock-state function retrieves whether the Num Lock modifier of the keyboard is locked, if object is a keyboard device.
See also:
2024-1-7
Accessor gdk:device-num-touches (object)
Syntax:
(gdk:device-num-touches object) => num-touches
Arguments:
object -- a gdk:device object
num-touches -- an unsigned integer with the number of touch points
Details:
Accessor of the num-touches slot of the gdk:device class. The gdk:device-num-touches function retrieves the number of touch points associated to the device.
See also:
2024-1-7
Accessor gdk:device-product-id (object)
Syntax:
(gdk:device-product-id object) => product-id
Arguments:
object -- a gdk:device object
product-id -- a string with the product ID, or nil
Details:
Accessor of the product-id slot of the gdk:device class. The gdk:device-product-id function returns the product ID of the device, or nil if the information could not be obtained. The ID is retrieved from the device, and is thus constant for it. See the gdk:device-vendor-id function for more information.
See also:
2024-1-7
Accessor gdk:device-scroll-lock-state (object)
Syntax:
(gdk:device-scroll-lock-id object) => setting
Arguments:
object -- a gdk:device object
scroll-lock-id -- true if Scroll Lock is on for the device
Details:
Accessor of the scroll-lock-state slot of the gdk:device class. The gdk:device-scroll-lock-state function retrieves whether the Scroll Lock modifier of the keyboard is locked, if object is a keyboard device.
See also:
2024-1-7
Accessor gdk:device-seat (object)
Syntax:
(gdk:device-seat object) => seat
(setf (gdk:device-seat object) seat)
Arguments:
object -- a gdk:device object
seat -- a gdk:seat object
Details:
Accessor of the seat slot of the gdk:device class. The gdk:device-seat function returns the seat the device belongs to. The (setf gdk:device-seat) function sets the seat.
See also:
2024-1-7
Accessor gdk:device-source (object)
Syntax:
(gdk:device-source object) => source
Arguments:
object -- a gdk:device object
source -- a gdk:input-source value
Details:
Accessor of the source slot of the gdk:device class. The gdk:device-source function determines the type of the device.
See also:
2024-1-7
Accessor gdk:device-tool (object)
Syntax:
(gdk:device-tool object) => tool
Arguments:
object -- a gdk:device object
tool -- a gdk:device-tool object
Details:
Accessor of the tool slot of the gdk:device class. The gdk:device-tool function retrieves the device tool associated to the device.
See also:
2024-1-7
Accessor gdk:device-vendor-id (object)
Syntax:
(gdk:device-vendor-id object) => vendor-id
Arguments:
object -- a gdk:device object
vendor-id -- a string with the vendor ID, or nil
Details:
Accessor of the vendor-id slot of the gdk:device class. The gdk:device-vendor-id function returns the vendor ID of this device, or nil if the information could not be obtained. This ID is retrieved from the device, and is thus constant for it.
See also:
2024-1-7
Function gdk:device-surface-at-position (device)
Arguments:
device -- a gdk:device object
Returns:
surface -- a gdk:surface object under the device position
xwin -- a double float with the x coordinate of the device location
ywin -- a double float with the y coordinate of the device location
Details:
Obtains the surface underneath device, returning the location of the device in xwin and ywin in double precision. Returns nil if the surface tree under device is not known to GDK, for example, belongs to another application.
See also:
2024-1-7
Function gdk:device-timestamp (device)
Arguments:
device -- a gdk:device object
Returns:
The unsigned integer with the timestamp of the last activity for this device.
Details:
Returns the timestamp of the last activity for this device. In practice, this means the timestamp of the last event that was received from the OS for this device. GTK may occasionally produce events for a device that are not received from the OS, and will not update the timestamp.

Since 4.2
See also:
2024-1-7

GdkDevicePad

GEnum gdk:device-pad-feature
Declaration:
(gobject:define-genum "GdkDevicePadFeature" device-pad-feature
  (:export t
   :type-initializer "gdk_device_pad_feature_get_type")
  :button
  :ring
  :strip)  
Values:
:button
A button.
:ring
A ring-shaped interactive area.
:strip
A straight interactive area.
Details:
A pad feature.
See also:
2025-2-28
Interface gdk:device-pad
Superclasses:
gdk:device, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:device-pad interface is an interface implemented by devices of :tablet-pad type of the gdk:input-source enumeration. 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. The gdk:device-pad-n-groups function can be used to obtain the number of groups, the gdk:device-pad-n-features and gdk:device-pad-feature-group functions 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 the gdk:device-pad-group-n-modes function, and the current mode for a given group will be notified through events of :pad-group-mode type of the gdk:event-type enumeration.
See also:
2025-2-28
Function gdk:device-pad-n-groups (pad)
Arguments:
pad -- a gdk:device-pad object
Returns:
The integer with the number of button/ring/strip groups in the pad device.
Details:
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.
See also:
#2025-2-28
Function gdk:device-pad-group-n-modes (pad index)
Arguments:
pad -- a gdk:device-pad object
index -- an integer for the group to get the number of available modes from
Returns:
The integer with the number of modes available in the group,
Details:
Returns the number of modes that the group may have.
See also:
#2025-2-28
Function gdk:device-pad-n-features (pad feature)
Arguments:
pad -- a gdk:device-pad object
feature -- a gdk:device-pad-feature value for the pad feature
Returns:
The integer with the amount of elements of type feature that this pad has.
Details:
Returns the number of features a tablet pad has.
See also:
#2025-2-28
Function gdk:device-pad-feature-group (pad feature index)
Arguments:
pad -- a gdk:device-pad object
feature -- a gdk:device-pad-feature value for the pad feature to get the group from
index -- an integer for the index of the feature to get the group from
Returns:
The integer with the group number of the queried pad feature.
Details:
Returns the group the given feature and index belong to, or -1 if feature/index do not exist in pad .
See also:
#2025-2-28

GdkMonitor

GEnum gdk:subpixel-layout
Declaration:
(gobject:define-genum "GdkSubpixelLayout" subpixel-layout
  (:export t
   :type-initializer "gdk_subpixel_layout_get_type")
  (:unknown 0)
  (:none 1)
  (:horizontal-rgb 2)
  (:horizontal-bgr 3)
  (:vertical-rgb 3)
  (:vertical-brg 4))  
Values:
:unknown
The layout is not known.
:none
Not organized in this way.
:horizontal-rgb
The layout is horizontal, the order is RGB.
:horizontal-bgr
The layout is horizontal, the order is BGR.
:vertical-rgb
The layout is vertical, the order is RGB.
:vertical-bgr
The layout is vertical, the order is BGR.
Details:
This enumeration describes how the red, green and blue components of physical pixels on an output device are laid out.
See also:
2024-5-26
Class gdk:monitor
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
connector
The connector property of type :string (Read)
The connector name.
Default value: nil
description
The description property of type :string (Read)
The short description of the monitor, meant for display to the user. Since 4.10
Default value: nil
display
The display property of type gdk:display (Read / Write / Construct only)
The display of the monitor.
geometry
The geometry property of type gdk:rectangle (Read)
The geometry of the monitor.
height-mm
The height-mm property of type :int (Read)
The height of the monitor, in millimeters.
Allowed values: >= 0
Default value: 0
manufacturer
The manufacturer property of type :string (Read)
The manufucturer name.
Default value: nil
model
The model property of type :string (Read)
The model name.
Default value: nil
refresh-rate
The refresh-rate property of type :int (Read)
The refresh rate, in millihertz.
Allowed values: >= 0
Default value: 0
scale
The scale property of type :int (Read)
The scale of the monitor. Since 4.14
Default value: 1.0
scale-factor
The scale-factor property of type :int (Read)
The scale factor.
Allowed values: >= 0
Default value: 1
subpixel-layout
The subpixel-layout property of type gdk:subpixel-layout (Read)
The subpixel layout.
Default value: :unknown
valid
The valid property of type :boolean (Read)
Whether the monitor is still valid.
Default value: true
width-mm
The width-mm property of type :int (Read)
The width of the monitor, in millimeters.
Allowed values: >= 0
Default value: 0
Slot Access Functions:
Details:
The gdk:monitor objects represent the individual outputs that are associated with a gdk:display object. The gdk:display object keeps a g:list-model instance to enumerate and monitor monitors with the gdk:display-monitors function. You can use the gdk:display-monitor-at-surface function to find a particular monitor.
Signal Details:
The "invalidate" signal
lambda (monitor)    :run-first      
monitor
The gdk:monitor object on which this signal was emitted.
The signal gets emitted when the output represented by monitor gets disconnected.
See also:
2024-5-25
Accessor gdk:monitor-connector (object)
Syntax:
(gdk:monitor-connector object) => connector
Arguments:
object -- a gdk:monitor object
connector -- a string with the name of the connector
Details:
Accessor of the connector slot of the gdk:monitor class. The gdk:monitor-connector function gets the name of the monitor's connector, if available.
See also:
2023-4-11
Accessor gdk:monitor-display (object)
Syntax:
(gdk:monitor-display object) => display
(setf (gdk:monitor-display object) display)
Arguments:
object -- a gdk:monitor object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:monitor class. The gdk:monitor-display function gets the display that this monitor belongs to.
See also:
2023-4-11
Accessor gdk:monitor-geometry (object)
Syntax:
(gdk:monitor-geometry object) => geometry
Arguments:
object -- a gdk:monitor object
geometry -- a gdk:rectangle instance with the monitor geometry
Details:
Accessor of the geometry slot of the gdk:monitor class. The gdk:monitor-geometry function 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 the gdk:monitor-scale-factor function.
See also:
2023-4-11
Accessor gdk:monitor-height-mm (object)
Syntax:
(gdk:monitor-height-mm object) => height
Arguments:
object -- a gdk:monitor object
height -- an integer with physical height of the monitor
Details:
Accessor of the height-mm slot of the gdk:monitor class. The gdk:monitor-height-mm function gets the height in millimeters of the monitor.
See also:
2023-4-11
Accessor gdk:monitor-manufacturer (object)
Syntax:
(gdk:monitor-manufacturer object) => manufacturer
Arguments:
object -- a gdk:monitor object
manufacturer -- a string with the name of the manufacturer, or nil
Details:
Accessor of the manufacturer slot of the gdk:monitor class. The gdk:monitor-manufacturer function gets the name or PNP ID of the monitor's manufacturer, if available. Note that this value might also vary depending on actual display backend. PNP ID registry is located at https://uefi.org/pnp_id_list.
See also:
2023-4-11
Accessor gdk:monitor-model (object)
Syntax:
(gdk:monitor-model object) => model
Arguments:
object -- a gdk:monitor object
model -- a string with the monitor model, or nil
Details:
Accessor of the model slot of the gdk:monitor class. The gdk:monitor-model function gets the string identifying the monitor model, if available.
See also:
2023-4-11
Accessor gdk:monitor-refresh-rate (object)
Syntax:
(gdk:monitor-refresh-rate object) => rate
Arguments:
object -- a gdk:monitor object
rate -- an integer with the refresh rate in milli-Hertz, or 0
Details:
Accessor of the refresh-rate slot of the gdk:monitor class. The gdk:monitor-refresh-rate function 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.
See also:
2023-4-11
Accessor gdk:monitor-scale (object)
Syntax:
(gdk:monitor-scale object) => scale
Arguments:
object -- a gdk:monitor object
scale -- a double float with the scale
Details:
Gets the internal scale factor that maps from monitor coordinates to device pixels. This can be used if you want to create pixel based data for a particular monitor, but most of the time you are drawing to a surface where it is better to use the gdk:surface-scale function instead.

Since 4.14
See also:
2024-5-26
Accessor gdk:monitor-scale-factor (object)
Syntax:
(gdk:monitor-scale-factor object) => scale
Arguments:
object -- a gdk:monitor object
scale -- an integer with the scale factor
Details:
Accessor of the scale-factor slot of the gdk:monitor class. The gdk:monitor-scale-factor function 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 are drawing to a surface where it is better to use the gdk:surface-scale-factor function instead.
See also:
2023-4-11
Accessor gdk:monitor-subpixel-layout (object)
Syntax:
(gdk:monitor-subpixel-layout object) => layout
Arguments:
object -- a gdk:monitor object
layout -- a gdk:subpixel-layout value
Details:
Accessor of the subpixel-layout slot of the gdk:monitor class. The gdk:monitor-subpixel-layout function gets information about the layout of red, green and blue primaries for each pixel in this monitor, if available.
See also:
2023-4-11
Accessor gdk:monitor-valid (object)
Syntax:
(gdk:monitor-valid object) => valid
Arguments:
object -- a gdk:monitor object
valid -- an boolean whether the monitor is still valid
Details:
Accessor of the valid slot of the gdk:monitor class.
See also:
2023-4-11
Accessor gdk:monitor-width-mm (object)
Syntax:
(gdk:monitor-width-mm object) => width
Arguments:
object -- a gdk:monitor object
width -- an integer with physical width of the monitor
Details:
Accessor of the width-mm slot of the gdk:monitor class. The gdk:monitor-width-mm function gets the width in millimeters of the monitor.
See also:
2023-4-11
Function gdk:monitor-is-valid (monitor)
Arguments:
monitor -- a gdk:monitor object
Details:
Returns true if the monitor object corresponds to a physical monitor. The monitor becomes invalid when the physical monitor is unplugged or removed.
See also:
2024-1-7

GdkSeat

GFlags gdk:seat-capabilities
Declaration:
(gobject:define-gflags "GdkSeatCapabilities" seat-capabilities
  (:export t
   :type-initializer "gdk_seat_capabilities_get_type")
  (:none 0)
  (:pointer       #.(ash 1 0))
  (:touch         #.(ash 1 1))
  (:tablet-stylus #.(ash 1 2))
  (:keyboard      #.(ash 1 3))
  (:tablet-pad    #.(ash 1 4))
  (:all-pointing 7)
  (:all 31))  
Values:
:none
No input capabilities.
:pointer
The seat has a pointer,for example, mouse.
:touch
The seat has touchscreen(s) attached.
:tablet-stylus
The seat has drawing tablet(s) attached.
:keyboard
The seat has keyboard(s) attached.
:tablet-pad
The seat has drawing tablet pad(s) attached.
:all-pointing
The union of all pointing capabilities.
:all
The union of all capabilities.
Details:
Flags describing the seat capabilities.
See also:
2024-7-12
Class gdk:seat
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
display
The display property of type gdk:display (Read / Write / Construct)
The display of this seat.
Slot Access Functions:
Details:
The gdk:seat object represents a collection of input devices that belong to a user.
Signal Details:
The "device-added" signal
lambda (seat device)    :run-last      
seat
The gdk:seat object on which the signal is emitted.
device
The newly added gdk:device object.
The signal is emitted when a new input device is related to this seat.
The "device-removed" signal
lambda (seat device)    :run-last      
seat
The gdk:seat object on which the signal is emitted.
device
The just removed gdk:device object.
The signal is emitted when an input device is removed, for example, unplugged.
The "tool-added" signal
lambda (seat tool)    :run-last      
seat
The gdk:seat object on which the signal is emitted.
tool
The new gdk:device-tool object known to the seat.
The signal is emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device, that is on proximity with a tablet. The device will emit the "tool-changed" signal accordingly. A same tool may be used by several devices.
The "tool-removed" signal
lambda (seat tool)    :run-last      
seat
The gdk:seat object on which the signal is emitted.
tool
The just removed gdk:device-tool object.
The signal is emitted whenever a tool is no longer known to this seat.
See also:
2024-7-12
Accessor gdk:seat-display (object)
Syntax:
(gdk:seat-display object) => display
Arguments:
object -- a gdk:seat object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:seat class. The gdk:seat-display function returns the display this seat belongs to.
See also:
2024-7-12
Function gdk:seat-capabilities (seat)
Arguments:
seat -- a gdk:seat object
Returns:
The seat capabilities as a gdk:seat-capabilities value.
Details:
Returns the capabilities this gdk:seat object currently has.
See also:
2023-4-15
Function gdk:seat-pointer (seat)
Arguments:
seat -- a gdk:seat object
Returns:
The master gdk:device object with pointer capabilities.
Details:
Returns the master device that routes pointer events.
See also:
2024-7-12
Function gdk:seat-keyboard (seat)
Arguments:
seat -- a gdk:seat object
Returns:
The master gdk:device object with keyboard capabilities.
Details:
Returns the master device that routes keyboard events.
See also:
2024-7-12
Function gdk:seat-devices (seat capabilities)
Arguments:
seat -- a gdk:seat object
capabilities -- a gdk:seat-capabilities value to get the devices for
Returns:
The list of gdk:device objects.
Details:
Returns the devices that match the given capabilities.
See also:
2024-7-12
Function gdk:seat-tools (seat)
Arguments:
seat -- a gdk:seat object
Returns:
The list of gdk:device-tool objects.
Details:
Returns all gdk:device-tools objects that are known to the application.
See also:
2024-7-12

Paintables

GdkPaintable

GFlags gdk:paintable-flags
Declaration:
(gobject:define-gflags "GdkPaintableFlags" paintable-flags
  (:export t
   :type-initializer "gdk_paintable_flags_get_type")
  (:static-size #.(ash 1 0))
  (:static-contents #.(ash 1 1)))  
Values:
:static-size
The size is immutable. The "invalidate-size" signal will never be emitted.
:static-contents
The content is immutable. The "invalidate-contents" signal will never be emitted.
Details:
Flags about a gdk:paintable object. Implementations use these for optimizations such as caching.
See also:
2024-5-5
Class gdk:snapshot
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Base type for snapshot operations. The subclass of the gdk:snapshot class used by GTK is the gtk:snapshot class.
See also:
2023-7-30
Interface gdk:paintable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gdk:paintable interface is a simple interface used by GDK and GTK to represent objects that can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as ClutterContent, HTML/CSS Paint Sources, or SVG Paint Servers.

A gdk:paintable object can be snapshot at any time and size using the gdk:paintable-snapshot function. How the paintable interprets that size and if it scales or centers itself into the given rectangle is implementation defined, though if you are implementing a gdk:paintable object and do not know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

The contents that a gdk:paintable object produces may depend on the gdk:snapshot object passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A gdk:paintable object will however always produce the same output for the same snapshot.

A gdk:paintable object may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call the gdk:paintable-invalidate-contents function which will emit the "invalidate-contents" signal. If a paintable is known to never change its contents, it will set the :static-contents flag. If a consumer cannot deal with changing contents, it may call the gdk:paintable-current-image function which will return a static paintable and use that.

A paintable can report an intrinsic (or preferred) size or aspect ratio it wishes to be rendered at, though it does not have to. Consumers of the interface can use this information to layout thepaintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling the gdk:paintable-invalidate-size function which will emit the "invalidate-size" signal. And just like for contents, if a paintable is known to never change its size, it will set the :static-size flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: gdk:paintable-invalidate-contents, gdk:paintable-invalidate-size, gdk:paintable-new-empty.
Interface structure:
(gobject:define-vtable ("GdkPaintable" paintable)
  (:skip parent-instance (:struct g:type-interface))
  ;; Methods of the GdkPaintable interface
  (snapshot (:void (paintable (g:object paintable))
                   (snapshot (g:object snapshot))
                   (width :double)
                   (height :double)))
  (get-current-image ((g:object paintable) (paintable (g:object paintable))))
  (get-flags (paintable-flags (paintable (g:object paintable))))
  (get-intrinsic-width (:int (paintable (g:object paintable))))
  (get-intrinsic-height (:int (paintable (g:object paintable))))
  (get-intrinsic-aspect-ratio (:double (paintable (g:object paintable)))))    
The list of functions that can be implemented for the gdk:paintable interface. The following methods are provided and can be specialized for a subclass which derives from the gdk:paintable interface:
gdk:paintable-snapshot-impl
Method called from the gdk:paintable-snapshot function.
gdk:paintable-get-current-image-impl
Method called from the gdk:paintable-current-image function.
gdk:paintable-get-flags-impl
Method called from the gdk:paintable-flags function.
gdk:paintable-get-intrinsic-width-impl
Method called from the gdk:paintable-intrinsic-width function.
gdk:paintable-get-intrinsic-height-impl
Method called from the gdk:paintable-intrinsic-height function.
gdk:paintable-get-intrinsic-aspect-ratio-impl
Method called from the gdk:paintable-intrinsic-aspect-ratio function.
Note that apart from the gdk:paintable-snapshot-impl method, no method of this interface is mandatory to implement, though it is a good idea to implement the gdk:paintable-get-current-image-impl method for non-static paintables and the gdk:paintable-get-flags-impl method if the paintable is not dynamic as the default implementation returns no flags and that will make the implementation likely quite slow.
Examples:
This is a complete example for the implementation of a subclass which implements the gdk:paintable interface.
;; Implementation of a NUCLEAR-ICON subclass
(gobject:define-gobject-subclass "GdkNuclearIcon" nuclear-icon
  (:superclass g:object
   :export t
   :interfaces ("GdkPaintable"))
  ((rotation
    nuclear-icon-rotation
    "rotation" "gdouble" t t)))

;; This is the function that draws the actual icon (defun nuclear-snapshot (snapshot foreground background width height rotation) (let ((size (min width height)) (radius 0.3) (cr nil)) (graphene:with-rects ((rect1 0 0 width height) (rect2 (/ (- width size) 2.0) (/ (- height size) 2.0) size size)) (gtk:snapshot-append-color snapshot background rect1) (setf cr (gtk:snapshot-append-cairo snapshot rect2)) (cairo-set-source-rgba cr foreground) (cairo:translate cr (/ width 2.0) (/ height 2.0)) (cairo:scale cr size size) (cairo:rotate cr rotation) (cairo:arc cr 0 0 0.1 (- pi) pi) (cairo:fill cr) (setf (cairo:line-width cr) radius) (setf (cairo:dash cr 0.0) (list (/ (* radius pi) 3))) (cairo:arc cr 0 0 radius (- pi) pi) (cairo:stroke cr) (cairo:destroy cr))))

;; Here, we implement the methods required by the GdkPaintable interface (defmethod paintable-snapshot-impl ((paintable nuclear-icon) snapshot width height) (nuclear-snapshot snapshot (rgba-new :red 0 :green 0 :blue 0 :alpha 1) (rgba-new :red 0.9 :green 0.75 :blue 0.15 :alpha 1) width height (nuclear-icon-rotation paintable)))

(defmethod paintable-get-flags-impl ((paintable nuclear-icon)) (list :static-contents :static-size))
Signal Details:
The "invalidate-contents" signal
lambda (paintable)    :run-last      
paintable
The gdk:paintable object.
Emitted when the contents of the paintable change. Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing.
The "invalidate-size" signal
lambda (paintable)    :run-last      
paintable
The gdk:paintable object.
Emitted when the intrinsic size of the paintable changes. This means the values reported by at least one of the gdk:paintable-intrinsic-width, gdk:paintable-intrinsic-height or gdk:paintable-intrinsic-aspect-ratio function has changed. Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.
See also:
2025-3-2
Method gdk:paintable-snapshot-impl (paintable snapshot width height)
Details:
Method called from the gdk:paintable-snapshot function.
Default method:
(defmethod paintable-snapshot-impl ((paintable paintable) snapshot width height)
  (error "Paintable of type ~a  does not implement GDK:PAINTABLE-SNAPSHOT-IMPL"
         (g:type-name (g:type-from-instance paintable))))    
This method must be implemented for a subclass which implements the gdk:paintable interface. The default implementation signals an error. See the gdk:paintable-snapshot function for the syntax. The gdk:paintable documentation shows a complete example of implementing the interface.
See also:
2023-12-2
Method gdk:paintable-get-current-image-impl (paintable)
Details:
Method called from the gdk:paintable-current-image function.
Default method:
(defmethod paintable-get-current-image-impl ((paintable paintable))
  (if (not (set-difference '(:static-size :static-contents)
                           (paintable-get-flags-impl paintable)))
      ;; Paintable is immutable, return it
      paintable
      ;; Create a new paintable object
      (let ((width (paintable-get-intrinsic-width-impl paintable))
            (height (paintable-get-intrinsic-height-impl paintable)))
        (if (or (<= width 0) (<= height 0))
          (paintable-new-empty width height)
          (let ((snapshot (g:object-new "GtkSnapshot")))
            (paintable-snapshot paintable snapshot width height)
            ;; The GTK package is not availabe at this point. We call the
            ;; C function directly.
            (cffi:foreign-funcall "gtk_snapshot_free_to_paintable"
                                  (g:object snapshot) snapshot
                                  :pointer (cffi:null-pointer)))))))    
The implementation of this method is not mandatory. The default implementation returns the paintable itself, when it is a static paintable. Otherwise, the default method returns an empty paintable or creates a paintable for the intrinsic width and height.
See also:
2023-12-2
Method gdk:paintable-get-flags-impl (paintable)
Details:
Method called from the gdk:paintable-flags function.
Default method:
(defmethod paintable-get-flags-impl ((paintable paintable))
  '())    
The default method returns no flags set.
See also:
2023-12-2
Method gdk:paintable-get-intrinsic-width-impl (paintable)
Details:
Method called from the gdk:paintable-intrinsic-width function.
Default method:
(defmethod paintable-get-intrinsic-width-impl ((paintable paintable))
  0)    
The default method returns 0 for the intrinsic width.
See also:
2023-12-2
Method gdk:paintable-get-intrinsic-height-impl (paintable)
Details:
Method called from the gdk:paintable-intrinsic-height function.
Default method:
(defmethod paintable-get-intrinsic-height-impl ((paintable paintable))
  0)    
The default method returns 0 for the intrinsic height.
See also:
2023-12-2
Method gdk:paintable-get-intrinsic-aspect-ratio-impl (paintable)
Details:
Method called from the gdk:paintable-intrinsic-aspect-ratio function.
Default method:
(defmethod paintable-get-intrinsic-aspect-ratio-impl ((paintable paintable))
  (let ((width (paintable-get-intrinsic-width-impl paintable))
        (height (paintable-get-intrinsic-height-impl paintable)))
    (if (or (<= width 0) (<= height 0))
        0.0d0
        (coerce (/ width height) 'double-float))))    
The default method returns 0.0d0 or the width to height ratio as a double float.
See also:
2023-12-2
Function gdk:paintable-current-image (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The immutable gdk:paintable object for the current contents of paintable.
Details:
Gets an immutable paintable for the current contents displayed by paintable. This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation. If the paintable is already immutable, it will return itself.
See also:
#2024-5-5
Function gdk:paintable-snapshot (paintable snapshot width height)
Arguments:
paintable -- a gdk:paintable object
snapshot -- a gdk:snapshot object
width -- a number coerced to a double float for the width to snapshot in
height -- a number coerced to a double float for the height to snapshot in
Returns:
The gdk:snapshot object to snapshot to.
Details:
Snapshots the given paintable with the given width and height at the current (0,0) offset of the snapshot. If width and height are not larger than zero, this function will do nothing.
See also:
2025-2-16
Function gdk:paintable-flags (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The gdk:paintable-flags value for this paintable.
Details:
Get flags for the paintable. This is oftentimes useful for optimizations. See the gdk:paintable-flags documentation for the flags and what they mean.
See also:
2024-5-5
Function gdk:paintable-intrinsic-width (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The integer with the the intrinsic width of paintable or 0 if none.
Details:
Gets the preferred width the paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to the gdk:paintable-snapshot function.

If the paintable does not have a preferred width, it returns 0. Negative values are never returned.
See also:
2024-5-5
Function gdk:paintable-intrinsic-height (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The integer with the the intrinsic height of paintable or 0 if none.
Details:
Gets the preferred height the paintable would like to be displayed at. Consumers of this interface can use this to reserve enough space to draw the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to the gdk:paintable-snapshot function.

If the paintable does not have a preferred height, it returns 0. Negative values are never returned.
See also:
2024-5-5
Function gdk:paintable-intrinsic-aspect-ratio (paintable)
Arguments:
paintable -- a gdk:paintable object
Returns:
The double float with the intrinsic aspect ratio of paintable or 0 if none.
Details:
Gets the preferred aspect ratio the paintable would like to be displayed at. The aspect ratio is the width divided by the height, so a value of 0.5 means that the paintable prefers to be displayed twice as high as it is wide. Consumers of this interface can use this to preserve aspect ratio when displaying the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to the gdk:paintable-snapshot function.

Usually when a paintable returns nonzero values from the gdk:paintable-intrinsic-width and gdk:paintable-intrinsic-height functions the aspect ratio should conform to those values, though that is not required.

If the paintable does not have a preferred aspect ratio, it returns 0. Negative values are never returned.
See also:
2024-5-5
Function gdk:paintable-compute-concrete-size (paintable swidth sheight dwidth dheight)
Arguments:
paintable -- a gdk:paintable object
swidth -- a double float with the width paintable could be drawn into or 0.0 if unknown
sheight -- a double float with the height paintable could be drawn into or 0.0 if unknown
dwidth -- a double float with the width paintable would be drawn into if no other constraints were given
dheight -- a double float with the height paintable would be drawn into if no other constraints were given
Returns:
cwidth - a double float with the concrete width computed
cheight - a double float with the concrete height computed
Details:
Applies the sizing algorithm outlined in https://drafts.csswg.org/css-images-3/default-sizing to the given paintable. See that link for more details.

It is not necessary to call this function when both swidth and sheight are known, but it is useful to call this function in GtkWidget:measure implementations to compute the other dimension when only one dimension is given.
See also:
#2023-8-1
Function gdk:paintable-invalidate-contents (paintable)
Arguments:
paintable -- a gdk:paintable object
Details:
Called by implementations of a gdk:paintable subclass to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls of the gdk:paintable-snapshot function produce the same output.

This function will emit the "invalidate-contents" signal. If a paintable reports the :static-contents value of the gdk:paintable-flags flags, it must not call this function.
See also:
2025-3-2
Function gdk:paintable-invalidate-size (paintable)
Arguments:
paintable -- a gdk:paintable object
Details:
Called by implementations of gdk:paintable subclasses to invalidate their size. As long as the size is not invalidated, paintable must return the same values for its intrinsic width, height and aspect ratio.

This function will emit the "invalidate-size" signal. If a paintable reports the :static-size flag, it must not call this function.
See also:
#2023-8-1
Function gdk:paintable-new-empty (width height)
Arguments:
width -- an integer with the intrinsic width to report. Can be 0 for no width
height -- an integer with the intrinsic height to report. Can be 0 for no height
Returns:
The new gdk:paintable object.
Details:
Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the GdkPaintableInterface.get_current_image() virtual function when the paintable is in an incomplete state.
See also:
#2024-5-5

GdkTexture

Constant gdk:+memory-default+
Details:
The default gdk:memory-format value for the memory format used by GTK. This is the format provided by the gdk:texture-download function. It is equal to the :argb32 value of the cairo:format-t enumeration.

Be aware that this format is different for different endianness.
See also:
2025-3-11
GEnum gdk:memory-format
Declaration:
(gobject:define-genum "GdkMemoryFormat" memory-format
  (:export t
   :type-initializer "gdk_memory_format_get_type")
  :B8G8R8A8-PREMULTIPLIED
  :A8R8G8B8-PREMULTIPLIED
  :R8G8B8A8-PREMULTIPLIED
  :B8G8R8A8
  :A8R8G8B8
  :R8G8B8A8
  :A8B8G8R8
  :R8G8B8
  :B8G8R8
  :R16G16B16
  :R16G16B16A16-PREMULTIPLIED
  :R16G16B16A16
  :R16G16B16-FLOAT
  :R16G16B16A16-FLOAT-PREMULTIPLIED
  :R16G16B16A16-FLOAT
  :R32G32B32-FLOAT
  :R32G32B32A32-FLOAT-PREMULTIPLIED
  :R32G32B32A32-FLOAT
  :8A8-PREMULTIPLIED
  :G8A8
  :G8
  :G16A16-PREMULTIPLIED
  :G16A16
  :G16
  :A8
  :A16
  :A16-FLOAT
  :A32-FLOAT
  :A8B8G8R8-PREMULTIPLIED
  :B8G8R8X8
  :X8R8G8B8
  :R8G8B8X8
  :X8B8G8R8
  :N-FORMATS)  
Values:
:B8G8R8A8-PREMULTIPLIED
4 bytes for blue, green, red, alpha. The color values are premultiplied with the alpha value. This is the default memory format for little endianness.
:A8R8G8B8-PREMULTIPLIED
4 bytes for alpha, red, green, blue. The color values are premultiplied with the alpha value. This is the default memory format for big endianness.
:R8G8B8A8-PREMULTIPLIED
4 bytes for red, green, blue, alpha The color values are premultiplied with the alpha value.
:B8G8R8A8
4 bytes for blue, green, red, alpha.
:A8R8G8B8
4 bytes for alpha, red, green, blue.
:R8G8B8A8
4 bytes for red, green, blue, alpha.
:A8B8G8R8
4 bytes for alpha, blue, green, red.
:R8G8B8
3 bytes for red, green, blue. The data is opaque.
:B8G8R8
3 bytes for blue, green, red. The data is opaque.
:R16G16B16
3 guint16 values for red, green, blue. Since 4.6
:R16G16B16A16-PREMULTIPLIED
4 guint16 values for red, green, blue, alpha. The color values are premultiplied with the alpha value. Since 4.6
:R16G16B16A16
4 guint16 values for red, green, blue, alpha. Since 4.6
:R16G16B16-FLOAT
3 half-float values for red, green, blue. The data is opaque. Since 4.6
:R16G16B16A16-FLOAT-PREMULTIPLIED
4 half-float values for red, green, blue and alpha. The color values are premultiplied with the alpha value. Since 4.6
:R16G16B16A16-FLOAT
4 half-float values for red, green, blue and alpha. Since 4.6
:R32G32B32-FLOAT
3 float values for red, green, blue.
:R32G32B32A32-FLOAT-PREMULTIPLIED
4 float values for red, green, blue and alpha. The color values are premultiplied with the alpha value. Since 4.6
:R32G32B32A32-FLOAT
4 float values for red, green, blue and alpha. Since 4.6
:8A8-PREMULTIPLIED
2 bytes for grayscale, alpha. The color values are premultiplied with the alpha value. Since 4.12
:G8A8
2 bytes for grayscale, alpha. Since 4.12
:G8
One byte for grayscale. The data is opaque. Since 4.12
:G16A16-PREMULTIPLIED
2 guint16 values for grayscale, alpha. The color values are premultiplied with the alpha value. Since 4.12
:G16A16
2 guint16 values for grayscale, alpha. Since 4.12
:G16
One guint16 value for grayscale. The data is opaque. Since 4.12
:A8
One byte for alpha. Since 4.12
:A16
One guint16 value for alpha. Since 4.12
:A16-FLOAT
One half-float value for alpha. Since 4.12
:A32-FLOAT
One float value for alpha. Since 4.12
:A8B8G8R8-PREMULTIPLIED
4 bytes for alpha, blue, green, red. The color values are premultiplied with the alpha value. Since 4.14
:B8G8R8X8
4 bytes for blue, green, red, unused. Since 4.14
:X8R8G8B8
4 bytes for unused, red, green, blue. Since 4.14
:R8G8B8X8
4 bytes for red, green, blue, unused. Since 4.14
:X8B8G8R8
4 bytes for unused, blue, green, red. Since 4.14
:N-FORMATS
The number of formats. This value will change as more formats get added, so do not rely on its concrete integer.
Details:
The gdk:memory-format enumeration describes a format that bytes can have in memory. It describes formats by listing the contents of the memory passed to it. So :A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so the :argb32 value of the cairo:format-t enumeration is represented by different memory format values on architectures with different endiannesses.

Its naming is modelled after VkFormat.
See also:
2025-3-11
Class gdk:texture
Superclasses:
gdk:paintable, gio:icon, gio:loadable-icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
color-state
The color-state property of type gdk:color-state (Read / Write / Construct only)
The color state of the texture. Since 4.16
height
The height property of type :int (Read / Write / Construct only)
The height of the texture, in pixels.
Allowed values: >= 1
Default value: 1
width
The width property of type :int (Read / Write / Construct only)
The width of the texture, in pixels.
Allowed values: >= 1
Default value: 1
Returned by:
Details:
The gdk:texture object is the basic element used to refer to pixel data. It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time.

There are various ways to create gdk:texture objects from a gdk-pixbuf:pixbuf object, or from bytes stored in memory, a file, or a g:resource instance.

The ownership of the pixel data is transferred to the gdk:texture instance. You can only make a copy of it, with the gdk:texture-download function.

The gdk:texture object is an immutable object: That means you cannot change anything about it other than increasing the reference count with the g:object-ref function.
See also:
2025-3-11
Accessor gdk:texture-color-state (object)
Syntax:
(gdk:texture-color-state object) => state
Arguments:
object -- a gdk:texture object
state -- a gdk:color-state instance
Details:
Accessor of the color-state slot of the gdk:texture class. The gdk:texture-color-state function returns the color state associated with the texture.

Since 4.16
See also:
2025-3-11
Accessor gdk:texture-height (object)
Syntax:
(gdk:texture-height object) => height
Arguments:
object -- a gdk:texture object
height -- an integer with the height of the texture
Details:
Accessor of the height slot of the gdk:texture class. The gdk:texture-height function returns the height of the texture , in pixels.
See also:
2025-3-11
Accessor gdk:texture-width (object)
Syntax:
(gdk:texture-width object) => width
Arguments:
object -- a gdk:texture object
width -- an integer with the width of the texture
Details:
Accessor of the width slot of the gdk:texture class. The gdk:texture-width function returns the width of the texture , in pixels.
See also:
2025-3-11
Function gdk:texture-new-for-pixbuf (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
Returns:
The newly created gdk:texture object.
Details:
Creates a new texture object representing pixbuf.
See also:
2025-3-11
Function gdk:texture-new-from-resource (path)
Arguments:
path -- a string for the path of the resource file
Returns:
The newly created gdk:texture object.
Details:
Creates a new texture by loading an image from a resource. The file format is detected automatically. The supported formats are PNG and JPEG, though more formats might be available.

It is a fatal error if path does not specify a valid image resource and the program will abort if that happens. If you are unsure about the validity of a resource, use the gdk:texture-new-from-file function to load it.
See also:
2025-3-11
Function gdk:texture-new-from-file (file)
Arguments:
file -- a g:file object to load
Returns:
The newly created gdk:texture object, or nil if an error occurred.
Details:
Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG and JPEG, though more formats might be available.
See also:
2025-3-11
Function gdk:texture-new-from-filename (path)
Arguments:
path -- a pathname or namestring for the file to load
Returns:
The newly created gdk:texture object.
Details:
Creates a new texture by loading an image from a file. The file format is detected automatically. The supported formats are PNG and JPEG, though more formats might be available.

This function is threadsafe, so that you can, for example, use the g:task object and the g:task-run-in-thread function to avoid blocking the main thread while loading a big image.

Since 4.6
See also:
2025-3-11
Function gdk:texture-new-from-bytes (bytes)
Arguments:
bytes -- a g:bytes instance containing data to load
Returns:
The newly created gdk:texture object.
Details:
Creates a new texture by loading an image from a memory. The file format is detected automatically. The supported formats are PNG, JPEG, and TIFF, though more formats might be available.

This function is threadsafe, so that you can, for example, use the g:task object and the g:task-run-in-thread function to avoid blocking the main thread while loading a big image.

Since 4.6
See also:
2025-3-11
Function gdk:texture-download (texture data stride)
Arguments:
texture -- a gdk:texture object
data -- a pointer to enough memory to be filled with the downloaded data of texture
stride -- an unsigned integer for the rowstride in bytes
Details:
Downloads the texture into local memory. This may be an expensive operation, as the actual texture data may reside on a GPU or on a remote display server.

The data format of the downloaded data is equivalent to the :argb32 value of the cairo:format-t enumeration, so every downloaded pixel requires 4 bytes of memory.
Examples:
Downloading a texture into a Cairo image surface:
(let ((surface (cairo:image-surface-create :argb32
                                           (gdk:texture-width texture)
                                           (gdk:texture-height texture))))
  (gdk:texture-download texture
                        (cairo:image-surface-data surface)
                        (cairo:image-surface-stride surface))
  (cairo:surface-mark-dirty surface)
  ... )    
See also:
2025-3-11
Function gdk:texture-save-to-png (texture filename)
Arguments:
texture -- a gdk:texture object
filename -- a string for the filename to store to
Returns:
True if saving succed, false on failure.
Details:
Store the given texture to the filename as a PNG file. This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a g:file object or other location, you might want to look into using the GdkPixbuf library.
See also:
#2025-3-11
Function gdk:texture-save-to-png-bytes (texture)
Arguments:
texture -- a gdk:texture object
Returns:
The newly allocated g:bytes instance containing PNG data.
Details:
Store the given texture in memory as a PNG file. Use the gdk:texture-new-from-bytes function to read it back.

If you want to serialize a texture, this is a convenient and portable way to do that. If you need more control over the generated image, such as attaching metadata, you should look into an image handling library such as the GdkPixbuf library. If you are dealing with high dynamic range float data, you might also want to consider the gdk:texture-save-to-tiff-bytes function instead.

Since 4.6
See also:
2025-3-11
Function gdk:texture-save-to-tiff (texture filename)
Arguments:
texture -- a gdk:texture object
filename -- a string for the filename to store to
Returns:
True if saving succeeded, false on failure.
Details:
Store the given texture to the filename as a TIFF file. GTK will attempt to store data without loss.

Since 4.6
See also:
#2025-3-11
Function gdk:texture-save-to-tiff-bytes (texture)
Arguments:
texture -- a gdk:texture object
Returns:
The newly allocated g:bytes instance containing TIFF data.
Details:
Store the given texture in memory as a TIFF file. Use the gdk:texture-new-from-bytes function to read it back.

This function is intended to store a representation of the texture’s data that is as accurate as possible. This is particularly relevant when working with high dynamic range images and floating-point texture data.

If that is not your concern and you are interested in a smaller size and a more portable format, you might want to use the gdk:texture-save-to-png-bytes function.

Since 4.6
See also:
2025-3-11
Function gdk:texture-format (texture)
Arguments:
texture -- a gdk:texture object
Returns:
The gdk:memory-format value with the preferred format for the data of the texture.
Details:
Gets the memory format most closely associated with the data of the texture. Note that it may not be an exact match for texture data stored on the GPU or with compression.

The format can give an indication about the bit depth and opacity of the texture and is useful to determine the best format for downloading the texture.

Since 4.10
See also:
2025-3-11
Class gdk:memory-texture
Superclasses:
gdk:texture, gdk:paintable, gio:icon, gio:loadable-icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:memory-texture class is a gdk:texture implementation representing image data in memory.
See also:
2025-3-11
Function gdk:memory-texture-new (width height format bytes stride)
Arguments:
width -- an integer for the width of the texture
height -- an integer for the height of the texture
format -- a gdk:memory-format value for the format of the data
bytes -- a g:bytes instance containing the pixel data
stride -- an integer for the rowstride of the data
Returns:
The newly created gdk:texture object.
Details:
Creates a new texture for a blob of image data. The g:bytes instance must contain stride x height pixels in the given format.
See also:
2025-3-11

GdkTextureDownloader

GBoxed gdk:texture-downloader
Declaration:
(glib:define-gboxed-opaque texture-download "GdkTextureDownloader"
  :export t
  :type-initializer "gdk_texture_downloader_get_type"
  :alloc (error "GdkTextureDownloader cannot be created from the Lisp side."))  
Returned by:
Details:
The gdk:texture-downloader structure is used to download the contents of a gdk:texture object. It is intended to be created as a short-term object for a single download, but can be used for multipe downloads of different textures or with different settings.

The gdk:texture-downloader structure can be used to convert data between different formats. Create a gdk:texture object for the existing format and then download it in a different format.

Since 4.10
See also:
2024-11-28
Function gdk:texture-downloader-new (texture)
Arguments:
texture -- a gdk:texture object to download
Returns:
The new gdk:texture-downloader instance.
Details:
Creates a new texture downloader for texture. By default, the downloader will convert the data to the default memory format, and to the sRGB color state.

Since 4.10
See also:
2024-12-2
Function gdk:texture-downloader-copy (downloader)
Arguments:
downloader -- a gdk:texture-downloader instance
Returns:
The gdk:texture-downloader object with a copy.
Details:
Creates a copy of the downloader

Since 4.10
See also:
#2024-12-2
Function gdk:texture-downloader-download-bytes (downloader)
Arguments:
downloader -- a gdk:texture-downloader instance
stride -- an unsigned integer with the stride of the resulting data in bytes
Returns:
The g:bytes instance with the downloaded pixels.
Details:
Downloads the given texture pixels into a g:bytes instance. The rowstride will be stored in the stride value.

This function will abort if it tries to download a large texture and fails to allocate memory. If you think that may happen, you should handle memory allocation yourself and use the gdk:texture-downloader-download-into function once allocation succeeded.

Since 4.10
See also:
#2024-12-2
Function gdk:texture-downloader-download-into (downloader data stride)
Arguments:
downloader -- a gdk:texture-downloader instance
data -- a pointer to enough memory to be filled with the downloaded data of the texture
stride -- an unsigned integer with the rowstrides in bytes
Details:
Downloads the texture into local memory.

Since 4.10
See also:
#2024-12-2
Function gdk:texture-downloader-color-state (downloader)
Syntax:
(gdk:texture-downloader-color-state downloader) => state
(setf (gdk:texture-downloader-color-state downloader) state)
Arguments:
downloader -- a gdk:texture-downloader instance
state -- a gdk:color-state instance with the color state to use
Details:
Sets the color state the downloader will convert the data to. By default, the sRGB colorstate returned by the gdk:color-state-srgb function is used.

Since 4.16
See also:
2024-12-2
Function gdk:texture-downloader-format (downloader)
Syntax:
(gdk:texture-downloader-format downloader) => format
(setf (gdk:texture-downloader-format downloader) format)
Arguments:
downloader -- a gdk:texture-downloader instance
format -- a gdk:memory-format value with the format to use
Details:
Sets the format the downloader will download. By default, the :default value is set.

Since 4.10
See also:
2024-12-2
Function gdk:texture-downloader-texture (downloader)
Syntax:
(gdk:texture-downloader-texture downloader) => texture
(setf (gdk:texture-downloader-texture downloader) texture)
Arguments:
downloader -- a gdk:texture-downloader instance
texture -- a gdk:texture object to download
Details:
Changes the texture the downloader will download.

Since 4.10
See also:
2024-12-2

GdkDmabufTexture

Class gdk:dmabuf-texture
Superclasses:
gdk:texture, gdk:paintable, gio:icon, gio:loadable-icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:dmabuf-texture class is a gdk:texture implementation representing a DMA buffer. To create a gdk:dmabuf-texture object, use the auxiliary gdk:dmabuf-texture-builder object.

Dma-buf textures can only be created on Linux.

Since 4.14
See also:
2025-2-22
Class gdk:dmabuf-texture-builder
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
display
The display property of type gdk:display (Read / Write)
The display that this texture will be used on.
fourcc
The fourcc property of type guint (Read / Write)
The format of the texture, as a fourcc value.
height
The height property of type guint (Read / Write)
The height of the texture.
Default value: 0
modifier
The modifier property of type guint64 (Read / Write)
The modifier.
Default value: 0
n-planes
The n-planes property of type guint (Read / Write)
The number of planes of the texture. Note that you can set properties for other planes, but they will be ignored when constructing the texture.
premultiplied
The premultiplied property of type :boolean (Read / Write)
Whether the alpha channel is premultiplied into the others. Only relevant if the format has alpha.
Default value: true
update-region
The update-region property of type cairo:region-t (Read / Write)
The update region of update-texture value.
update-texture
The update-texture property of type gdk:texture (Read / Write)
The texture the update-region value is an update for.
width
The width property of type :uint (Read / Write)
The width of the texture.
Default value: 0
Details:
The gdk:dmabuf-texture-builder object is a builder used to construct gdk:texture objects from DMA buffers. DMA buffers are commonly called dma-bufs.

DMA buffers are a feature of the Linux kernel to enable efficient buffer and memory sharing between hardware such as codecs, GPUs, displays, cameras and the kernel drivers controlling them. For example, a decoder may want its output to be directly shared with the display server for rendering without a copy.

Any device driver which participates in DMA buffer sharing, can do so as either the exporter or importer of buffers (or both).

The memory that is shared via DMA buffers is usually stored in non-system memory (maybe in device’s local memory or something else not directly accessible by the CPU), and accessing this memory from the CPU may have higher-than-usual overhead.

In particular for graphics data, it is not uncommon that data consists of multiple separate blocks of memory, for example one block for each of the red, green and blue channels. These blocks are called planes. DMA buffers can have up to four planes. Even if the memory is a single block, the data can be organized in multiple planes, by specifying offsets from the beginning of the data.

DMA buffers are exposed to user-space as file descriptors allowing to pass them between processes. If a DMA buffer has multiple planes, there is one file descriptor per plane.

The format of the data (for graphics data, essentially its colorspace) is described by a 32-bit integer. These format identifiers are defined in the header file drm_fourcc.h and commonly referred to as fourcc values, since they are identified by 4 ASCII characters. Additionally, each DMA buffer has a modifier, which is a 64-bit integer that describes driver-specific details of the memory layout, such as tiling or compression.

For historical reasons, some producers of dma-bufs do not provide an explicit modifier, but instead return DMA_FORMAT_MOD_INVALID to indicate that their modifier is implicit. GTK tries to accommodate this situation by accepting DMA_FORMAT_MOD_INVALID as modifier.

The operation of the gdk:dmabuf-texture-builder object is quite simple: Create a texture builder, set all the necessary properties, and then call the gdk:dmabuf-texture-builder-build object to create the new texture.

The required properties for a dma-buf texture are
  • The width and height in pixels.
  • The fourcc code and modifier which identify the format and memory layout of the dma-buf.
  • The file descriptor, offset and stride for each of the planes.
GdkDmabufTextureBuilder can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures.

For further information, see the Linux kernel Linux kernel documentation and the drm_fourcc.h header file.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-display (object)
Syntax:
(gdk:dmabuf-texture-builder-display object) => display
(setf (gdk:dmabuf-texture-builder-display object) display)
Arguments:
object -- a gdk:dmabuf-texture-builder object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-display function returns the display that this texture builder is associated with. The (setf gdk:dmabuf-texture-builder-display) function sets the display. The display is used to determine the supported dma-buf formats.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-fourcc (object)
Syntax:
(gdk:dmabuf-texture-builder-fourcc object) => fourcc
(setf (gdk:dmabuf-texture-builder-fourcc object) fourcc)
Arguments:
object -- a gdk:dmabuf-texture-builder object
fourcc -- an integer with the format of the texture or 0 to unset
Details:
Accessor of the fourcc slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-fourcc function gets the format previously set or 0 if the format was not set. The gdk:dmabuf-texture-builder-fourcc function sets the format of the texture. The format is specified as a fourcc code.

The format must be set before calling the gdk:gl-texture-builder-build function.

Since 4.14
See also:
gdk:dmabuf-texture-builder
gdk:dmabuf-texture-builder-build
2024-7-11
Accessor gdk:dmabuf-texture-builder-height (object)
Syntax:
(gdk:dmabuf-texture-builder-height object) => height
(setf (gdk:dmabuf-texture-builder-height object) height)
Arguments:
object -- a gdk:dmabuf-texture-builder object
height -- an integer with the height of the texture or 0 to unset
Details:
Accessor of the height slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-height function gets the height previously set or 0 if the height was not set. The (setf gdk:dmabuf-texture-builder-height) function sets the height of the texture.

The height must be set before calling the gdk:gl-texture-builder-build function.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-modifier (object)
Syntax:
(gdk:dmabuf-texture-builder-modifier object) => modifier
(setf (gdk:dmabuf-texture-builder-modifier object) modifier)
Arguments:
object -- a gdk:dmabuf-texture-builder object
modifier -- an integer with the modifier value
Details:
Accessor of the height slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-modifier function gets the modifier value. The (setf gdk:dmabuf-texture-builder-modifier) function sets the modifier.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-n-planes (object)
Syntax:
(gdk:dmabuf-texture-builder-n-planes object) => n-planes
(setf (gdk:dmabuf-texture-builder-n-planes object) n-planes)
Arguments:
object -- a gdk:dmabuf-texture-builder object
n-planes -- an integer with the number of planes
Details:
Accessor of the n-planes slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-n-planes function gets the number of planes. The (setf gdk:dmabuf-texture-builder-n-planes) function sets the number of planes.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-premultiplied (object)
Syntax:
(gdk:dmabuf-texture-builder-premultiplied object) => premultiplied
(setf (gdk:dmabuf-texture-builder-premultiplied object) premultiplied)
Arguments:
object -- a gdk:dmabuf-texture-builder object
premultiplied -- a boolean whether the data is premultiplied
Details:
Accessor of the premultiplied slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-premultiplied function gets whether the data is premultiplied. The (setf gdk:dmabuf-texture-builder-premultiplied) function sets whether the data is premultiplied.

Unless otherwise specified, all formats including alpha channels are assumed to be premultiplied.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-update-region (object)
Syntax:
(gdk:dmabuf-texture-builder-update-region object) => region
(setf (gdk:dmabuf-texture-builder-update-region object) region)
Arguments:
object -- a gdk:dmabuf-texture-builder object
region -- a cairo:region-t instance
Details:
Accessor of the update-region slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-update-region function gets the region previously set or nil if none was set. The (setf gdk:dmabuf-texture-builder-update-region) function sets the region to be updated by this texture. Together with the update-texture property this describes an update of a previous texture.

When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change. An example would be a screen recording where only the mouse pointer moves.

Since 4.14
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-update-texture (object)
Syntax:
(gdk:dmabuf-texture-builder-update-texture object) => texture
(setf (gdk:dmabuf-texture-builder-update-region object) texture)
Arguments:
object -- a gdk:dmabuf-texture-builder object
texture -- a gdk:texture object
Details:
Accessor of the update-texture slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-update-texture function gets the texture previously set or nil if none was set. The (setf gdk:dmabuf-texture-builder-update-texture) function sets the texture to be updated by this texture. See the gdk:dmabuf-texture-builder-update-region function for an explanation.
See also:
2024-7-11
Accessor gdk:dmabuf-texture-builder-width (object)
Syntax:
(gdk:dmabuf-texture-builder-width object) => width
(setf (gdk:dmabuf-texture-builder-width object) width)
Arguments:
object -- a gdk:dmabuf-texture-builder object
width -- an integer with the width of the texture or 0 to unset
Details:
Accessor of the width slot of the gdk:dmabuf-texture-builder class. The gdk:dmabuf-texture-builder-width function gets the width previously set or 0 if the width was not set. The (setf gdk:dmabuf-texture-builder-width) function sets the width of the texture.

The width must be set before calling the gdk:gl-texture-builder-build function.

Since 4.14
See also:
2024-7-11
Function gdk:dmabuf-texture-builder-new ()
Returns:
Details:
Create a new texture builder.

Since 4.14
See also:
#2024-1-10

Surfaces, Toplevels, Popups

Surfaces

Class gdk:surface
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
cursor
The cursor property of type gdk:cursor (Read / Write)
The mouse pointer for a surface.
display
The display property of type gdk:display (Read / Write / Construct only)
The display connection of the surface.
frame-clock
The frame-clock property of type gdk:frame-clock (Read / Write / Construct only)
The frame clock for the surface.
height
The height property of type :int (Read)
The height of the surface.
Allowed values: >= 0
Default value: 0
mapped
The mapped property of type :boolean (Read)
Whether the surface is mapped.
Default value: false
scale
The scale property of type :double (Read)
The scale of the surface.
Default value: 1.0d0
scale-factor
The scale-factor property of type :int (Read)
The scale factor of the surface.
Allowed values: >= 1
Default value: 1
width
The width property of type :int (Read)
The width of the surface.
Allowed values: >= 0
Default value: 0
Returned by:
Slot Access Functions:
Details:
The gdk:surface object is a rectangular region on the screen. It is a low-level object, used to implement high-level objects such as the gtk:window or the gtk:dialog widgets in GTK.

The surfaces you see in practice are either gdk:toplevel or gdk:popup objects, and those interfaces provide much of the required API to interact with these surfaces. Other, more specialized surface types exist, but you will rarely interact with them directly.
Signal Details:
The "enter-monitor" signal
lambda (surface monitor)    :run-first      
surface
The gdk:surface object.
monitor
The gdk:monitor object.
Emitted when surface starts being present on the monitor.
The "event" signal
lambda (surface event)    :run-last      
surface
The gdk:surface object.
event
The gdk:event instance to an input event.
Returns
True to indicate that the event has been handled.
Emitted when GDK receives an input event for surface.
The "layout" signal
lambda (surface width height)    :run-first      
surface
The gdk:surface object.
width
The integer with the current width.
height
The integer with the current height.
Emitted when the size of surface is changed, or when relayout should be performed. The surface size is reported in "application pixels", not "device pixels". See the gdk:surface-scale-factor function.
The "leave-monitor" signal
lambda (surface monitor)    :run-first      
surface
The gdk:surface object.
monitor
The gdk:monitor object.
Emitted when surface stops being present on the monitor.
The "render" signal
lambda (surface region)    :run-last      
surface
The gdk:surface object.
region
The cairo:region-t instance that needs to be redrawn.
Returns
True to indicate that the signal has been handled.
Emitted when part of the surface needs to be redrawn.
See also:
2024-7-12
Accessor gdk:surface-cursor (object)
Syntax:
(gdk:surface-cursor object) => cursor
(setf (gdk:surface-cursor object) cursor)
Arguments:
object -- a gdk:surface object
cursor -- a gdk:cursor object
Details:
Accessor of the cursor slot of the gdk:surface class. The gdk:surface-cursor function retrieves the cursor currently set on the specified surface, or nil. If the return value is nil then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface. The (setf gdk:surface-cursor) function sets the default mouse pointer for a surface. Note that cursor must be for the same display as surface.

Use the gdk:cursor-new-from-name function or the gdk:cursor-new-from-texture function to create the cursor. To make the cursor invisible, use a blank cursor. Passing nil for the cursor argument means that the surface will use the cursor of its parent surface. Most surfaces should use this default.
See also:
2024-1-8
Accessor gdk:surface-display (object)
Syntax:
(gdk:surface-display object) => display
(setf (gdk:surface-display object) display)
Arguments:
object -- a gdk:surface object
display -- a gdk:display object associated with surface
Details:
Accessor of the display slot of the gdk:surface class. The gdk:surface-display function gets the display associated with the surface.
See also:
2024-1-8
Accessor gdk:surface-frame-clock (object)
Syntax:
(gdk:surface-frame-clock object) => clock
(setf (gdk:surface-frame-clock object) clock)
Arguments:
object -- a gdk:surface object
clock -- a gdk:frame-clock object
Details:
Accessor of the frame-clock slot of the gdk:surface class. The gdk:surface-frame-clock function gets the frame clock for the surface. The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface.
See also:
2024-1-8
Accessor gdk:surface-height (object)
Syntax:
(gdk:surface-height object) => height
(setf (gdk:surface-height object) height)
Arguments:
object -- a gdk:surface object
width -- an integer with the height of the surface
Details:
Accessor of the height slot of the gdk:surface class. The gdk:surface-height function returns the height of the given surface. Surface size is reported in "application pixels", not "device pixels". See the gdk:surface-scale-factor function.
See also:
2024-1-8
Accessor gdk:surface-mapped (object)
Syntax:
(gdk:surface-mapped object) => mapped
(setf (gdk:surface-mapped object) mapped)
Arguments:
object -- a gdk:surface object
mapped -- a boolean whether the surface has been mapped
Details:
Accessor of the mapped slot of the gdk:surface class. The gdk:surface-mapped function checks whether the surface has been mapped with the gdk:toplevel-present or gdk:popup-present functions.
See also:
2024-1-8
Accessor gdk:surface-scale (object)
Syntax:
(gdk:surface-scale object) => scale
(setf (gdk:surface-scale object) scale)
Arguments:
object -- a gdk:surface object
scale -- a double float with the scale
Details:
Accessor of the scale slot of the gdk:surface class. The gdk:surface-scale function returns the internal scale that maps from surface coordinates to the actual device pixels. When the scale is bigger than 1, the windowing system prefers to get buffers with a resolution that is bigger than the surface size, for example, to show the surface on a high-resolution display, or in a magnifier.

Compare with the gdk:surface-scale-factor function, which returns the next larger integer.

The scale may change during the lifetime of the surface.

Since 4.12
See also:
2024-1-8
Accessor gdk:surface-scale-factor (object)
Syntax:
(gdk:surface-scale-factor object) => factor
(setf (gdk:surface-scale-factor object) factor)
Arguments:
object -- a gdk:surface object
factor -- an integer with the scale factor
Details:
Accessor of the scale-factor slot of the gdk:surface class. The gdk:surface-scale-factor function returns the internal scale factor that maps from surface coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2).

A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data.

The scale of a surface may change during runtime.
See also:
2024-1-8
Accessor gdk:surface-width (object)
Syntax:
(gdk:surface-width object) => width
(setf (gdk:surface-width object) width)
Arguments:
object -- a gdk:surface object
width -- an integer with the width of the surface
Details:
Accessor of the width slot of the gdk:surface class. The gdk:surface-width function returns the width of the given surface. Surface size is reported in "application pixels", not "device pixels". See the gdk:surface-scale-factor function.
See also:
2024-1-8
Function gdk:surface-new-toplevel (display)
Arguments:
display -- a gdk:display object to create the surface on
Returns:
The new gdk:surface object.
Details:
Creates a new toplevel surface.
See also:
2024-12-19
Function gdk:surface-new-popup (parent autohide)
Arguments:
parent -- a gdk:surface object with the parent surface to attach the surface to
autohide -- a boolean whether to hide the surface on outside clicks
Returns:
The new gdk:surface object.
Details:
Creates a new popup surface. The surface will be attached to parent and can be positioned relative to it using the gdk:popup-present function.
See also:
2024-12-19
Function gdk:surface-destroy (surface)
Arguments:
surface -- a gdk:surface object
Details:
Destroys the window system resources associated with surface and decrements reference count of the surface. The window system resources for all children of the surface are also destroyed, but the reference counts of the children are not decremented.

Note that a surface will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens.
See also:
2024-1-8
Function gdk:surface-is-destroyed (surface)
Arguments:
surface -- a gdk:surface object
Returns:
True if the surface is destroyed.
Details:
Check to see if a surface is destroyed.
See also:
2024-1-8
Function gdk:surface-hide (surface)
Arguments:
surface -- a gdk:surface object
Details:
For toplevel surfaces, withdraws them, so they will no longer be known to the window manager. For all surfaces, unmaps them, so they will not be displayed. Normally done automatically as part of the gtk:widget-hide function.
See also:
#2023-4-8
Function gdk:surface-translate-coordinates (from to x y)
Arguments:
from -- a gdk:surface object with the origin surface
to -- a gdk:surface object with the target surface
x -- a number coerced to a double float with the x coordinate to translate
x -- a number coerced to a double float with the y coordinate to translate
Returns:
xnew -- a double float with the result for the x coordinate
ynew -- a double float with the result for the y coordinate
Details:
Translates the given coordinates from being relative to the from surface to being relative to the to surface. Note that this only works if to and from are popups or transient-for to the same toplevel (directly or indirectly).

The function returns nil, if the coordinates were not successfully translated.
See also:
#2024-7-12
Function gdk:surface-beep (surface)
Arguments:
surface -- a toplevel gdk:surface object
Details:
Emits a short beep associated to surface in the appropriate display, if supported. Otherwise, emits a short beep on the display just as the gdk:display-beep function.
See also:
#2023-4-8
Function gdk:surface-set-opaque-region (surface region)
Arguments:
surface -- a toplevel or non-native gdk:surface object
region -- a cairo:region-t instance, or nil
Details:
For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not. This function only works for toplevel surfaces.

GTK will update this property automatically if the surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your GtkWidgetClass.css_changed() handler.
Warning:
This function is deprecated since 4.16. GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.
See also:
#2024-11-7
Function gdk:surface-create-gl-context (surface)
Arguments:
surface -- a gdk:surface object
Returns:
The newly created gdk:gl-context object.
Details:
Creates a new OpenGL context matching the framebuffer format to the visual of the surface. The context is disconnected from any particular surface.

Before using the returned OpenGL context, you will need to call the gdk:gl-context-make-current or gdk:gl-context-realize function.
See also:
#2024-11-21
Function gdk:surface-create-cairo-context (surface)
Arguments:
surface -- a gdk:surface object
Returns:
The newly created gdk:cairo-context object.
Details:
Creates a new gdk:cairo-context object for rendering on surface.
See also:
#2023-7-30
Function gdk:surface-create-similar-surface (surface content width height)
Arguments:
surface -- a gdk:surface object to make the new surface similar to
content -- a cairo:content-t value for the content of the new surface
width -- an integer with the width of the new surface
height -- an integer with the height of the new surface
Returns:
A newly allocated cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid pointer, but it will return a "nil" surface if the surface is in an error state.
Details:
Creates a new surface that is as compatible as possible with the given surface. For example the new surface will have the same fallback resolution and font options as surface. Generally, the new surface will also use the same backend as surface, unless that is not possible for some reason. The type of the returned surface may be examined with the cairo:surface-type function.

Initially the surface contents are all 0, transparent if contents have transparency, black otherwise.
Warning:
The gdk:surface-create-similar-surface function is depreacted since 4.12. Create a suitable Cairo image surface yourself.
See also:
#2024-1-8
Function gdk:surface-queue-render (surface)
Arguments:
surface -- a gdk:surface object
Details:
Forces a "render" signal emission for surface to be scheduled. This function is useful for implementations that track invalid regions on their own.
See also:
#2023-4-8
Function gdk:surface-request-layout (surface)
Arguments:
surface -- a gdk:surface object
Details:
Request a layout phase from the frame clock of the surface. See the gdk:frame-clock-request-phase function.
See also:
#2023-4-8
Function gdk:surface-set-input-region (surface region)
Arguments:
surface -- a gdk:surface object
region -- a cairo:region-t instance with the region of surface to be reactive
Details:
Apply the region to the surface for the purpose of event handling. Mouse events which happen while the pointer position corresponds to an unset bit in the mask will be passed on the surface below surface.

An input region is typically used with RGBA surfaces. The alpha channel of the surface defines which pixels are invisible and allows for nicely antialiased borders, and the input region controls where the surface is "clickable".

Use the gdk:display-supports-input-shapes function to find out if a particular backend supports input regions.
See also:
#2023-4-8
Function gdk:surface-device-position (surface device)
Arguments:
surface -- a gdk:surface object
device -- a gdk:device object
Returns:
x -- a double float with the x coordinate of device
y -- a double float with the y coordinate of device
mask -- a gdk:modifier-type value
Details:
Obtains the current device position in doubles and modifier state. The position is given in coordinates relative to the upper left corner of surface. Returns false if the device is not over the surface.
See also:
#2023-4-8
Function gdk:surface-device-cursor (surface device)
Syntax:
(gdk:surface-device-cursor surface device) => cursor
(setf (gdk:surface-device-cursor surface device) cursor)
Arguments:
surface -- a gdk:surface object
device -- a gdk:device object
cursor -- a gdk:cursor object
Details:
The gdk:surface-device-cursor function retrieves a gdk:cursor pointer for the device currently set on the specified surface, or nil. If the return value is nil then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.

The (setf gdk:surface-device-cursor) function sets a specific cursor for a given device when it gets inside surface. Use the gdk:cursor-new-from-name or gdk:cursor-new-from-texture function to create the cursor. To make the cursor invisible, use a blank cursor. Passing nil for the cursor argument means that surface will use the cursor of its parent surface. Most surfaces should use this default.
See also:
#2023-4-8

GdkToplevelSize

CStruct gdk:toplevel-size
Details:
The gdk:toplevel-size structure contains information that may be useful for users of gdk:toplevel objects to compute a surface size. It also carries information back with the computational result.
See also:
#2023-4-10
Function gdk:toplevel-size-bounds (size)
Syntax:
(gdk:toplevel-size size) => width, height
Arguments:
size -- a gdk:toplevel-size instance
width -- an integer with the width
height -- an integer with the height
Details:
Retrieves the bounds the toplevel is placed within. The bounds represent the largest size a toplevel may have while still being able to fit within some type of boundary. Depending on the backend, this may be equivalent to the dimensions of the work area or the monitor on which the window is being presented on, or something else that limits the way a toplevel can be presented.
See also:
#2023-4-10
Function gdk:toplevel-size-set-size (size width height)
Arguments:
size -- a gdk:toplevel-size instance
width -- an integer with the width
height -- an integer with the height
Details:
Sets the size the toplevel prefers to be resized to. The size should be within the bounds, see the gdk:toplevel-size-bounds function. The set size should be considered as a hint, and should not be assumed to be respected by the windowing system, or backend.
See also:
#2023-4-10
Function gdk:toplevel-size-set-min-size (size width height)
Arguments:
size -- a gdk:toplevel-size instance
width -- an integer with the minimum width
height -- an integer with the minimum height
Details:
The minimum size corresponds to the limitations the toplevel can be shrunk to, without resulting in incorrect painting. A user of a gdk:toplevel object should calculate these given both the existing size, and the bounds retrieved from the gdk:toplevel-size object.

The minimum size should be within the bounds. see the gdk:toplevel-size-bounds function.
See also:
#2023-4-10
Function gdk:toplevel-size-set-shadow-width (size left right top bottom)
Arguments:
size -- a gdk:toplevel-size instance
left -- an integer with the width of the left part of the shadow
right -- an integer with the width of the right part of the shadow
top -- an integer with the height of the top part of the shadow
bottom -- an integer with the height of the bottom part of the shadow
Details:
The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would there be any.
See also:
#2023-4-10

GdkToplevelLayout

GBoxed gdk:toplevel-layout
Declaration:
(glib:define-gboxed-opaque toplevel-layout "GdkToplevelLayout"
  :type-initializer "gdk_toplevel_layout_get_type"
  :alloc (%toplevel-layout-new))  
Returned by:
Details:
Toplevel surfaces are sovereign windows that can be presented to the user in various states (maximized, on all workspaces, etc). The gdk:toplevel-layout structure contains information that is necessary to do so, and is passed to the gdk:toplevel-present function.
See also:
2024-1-9
Function gdk:toplevel-layout-new ()
Returns:
The newly created gdk:toplevel-layout instance.
Details:
Create a toplevel layout description. Used together with the gdk:toplevel-present function to describe how a toplevel surface should be placed and behave on-screen.

The size is in "application pixels", not "device pixels", see the gdk:surface-scale-factor function.
See also:
2024-1-9
Function gdk:toplevel-layout-copy (layout)
Arguments:
layout -- a gdk:toplevel-layout instance
Returns:
The gdk:toplevel-layout instance with the copy of layout.
Details:
Create a new gdk:toplevel-layout instance and copy the contents of layout into it.
See also:
2024-1-9
Function gdk:toplevel-layout-equal (layout other)
Arguments:
layout -- a gdk:toplevel-layout instance
other -- another gdk:toplevel-layout instance
Returns:
True if layout and other have identical layout properties, otherwise false.
Details:
Check whether layout and other have identical layout properties.
See also:
2024-1-9
Function gdk:toplevel-layout-maximized (layout)
Syntax:
(gdk:toplevel-layout-maximized layout) => maximized
(setf (gdk:toplevel-layout-maximized layout) maximized)
Arguments:
layout -- a gdk:toplevel-layout instance
maximized -- a boolean whether the toplevel should be maximized
Details:
If the layout specifies whether the toplevel should go maximized, the maximized argument is set to true if it should go fullscreen, or false, if it should go unmaximized.
See also:
2024-1-9
Function gdk:toplevel-layout-fullscreen (layout)
Syntax:
(gdk:toplevel-layout-fullscreen layout) => fullscreen
(setf (gdk:toplevel-layout-fullscreen layout) fullscreen)
Arguments:
layout -- a gdk:toplevel-layout instance
fullscreen -- a boolean whether the layout specifies the fullscreen state for the toplevel
Details:
If the layout specifies whether the toplevel should go fullscreen, the fullscreen value is set to true if it should go fullscreen, or false, if it should go unfullscreen.
See also:
2024-1-9
Function gdk:toplevel-layout-fullscreen-monitor (layout)
Arguments:
layout -- a gdk:toplevel-layout object
Returns:
The gdk:monitor object on which layout fullscreens.
Details:
Returns the monitor that the layout is fullscreening the surface on.
See also:
2024-1-9
Function gdk:toplevel-layout-resizable (layout)
Syntax:
(gdk:toplevel-layout-resizable layout) => resizable
(setf (gdk:toplevel-layout-resizable layout) resizable)
Arguments:
layout -- a gdk:toplevel-layout instance
resizable -- true if the layout is resizable
Details:
The gdk:toplevel-layout-resizable function returns whether the layout should allow the user to resize the surface. The (setf gdk:toplevel-layout-resizable) function sets whether the layout should allow the user to resize the surface after it has been presented.
See also:
2024-1-9

GdkToplevel

GFlags gdk:toplevel-state
Declaration:
(gobject:define-gflags "GdkToplevelState" toplevel-state
  (:export t
   :type-initializer "gdk_toplevel_state_get_type")
  (:minimized #.(ash 1 0))
  (:maximized #.(ash 1 1))
  (:sticky #.(ash 1 2))
  (:fullscreen #.(ash 1 3))
  (:above #.(ash 1 4))
  (:below #.(ash 1 5))
  (:focused #.(ash 1 6))
  (:tiled #.(ash 1 7))
  (:top-tiled #.(ash 1 8))
  (:top-resizable #.(ash 1 9))
  (:right-tiled #.(ash 1 10))
  (:right-resizable #.(ash 1 11))
  (:bottom-tiled #.(ash 1 12))
  (:bottom-resizable #.(ash 1 13))
  (:left-tiled #.(ash 1 14))
  (:left-resizable #.(ash 1 15)))  
Values:
:minimized
The surface is minimized.
:maximized
The surface is maximized.
:sticky
The surface is sticky.
:fullscreen
The surface is maximized without decorations.
:above
The surface is kept above other surfaces.
:below
The surface is kept below other surfaces.
:focused
The surface is presented as focused (with active decorations).
:tiled
The surface is in a tiled state.
:top-tiled
Whether the top edge is tiled.
:top-resizable
Whether the top edge is resizable.
:right-tiled
Whether the right edge is tiled.
:right-resizable
Whether the right edge is resizable.
:bottom-tiled
Whether the bottom edge is tiled.
:bottom-resizable
Whether the bottom edge is resizable.
:left-tiled
Whether the left edge is tiled.
:left-resizable
Whether the left edge is resizable.
Details:
Specifies the state of a toplevel surface. On platforms that support information about individual edges, the :state-tiled state will be set whenever any of the individual tiled states is set. On platforms that lack that support, the tiled state will give an indication of tiledness without any of the per-edge states being set.
See also:
2024-7-12
GEnum gdk:fullscreen-mode
Declaration:
(gobject:define-genum "GdkFullscreenMode" fullscreen-mode
  (:export t
   :type-initializer "gdk_fullscreen_mode_get_type")
  (:on-current-monitor 0)
  (:on-all-monitor 1))  
Values:
:on-current-monitor
Fullscreen on current monitor only.
:on-all-monitor
Span across all monitors when fullscreen.
Details:
Indicates which monitor (in a multi-head setup) a surface should span over when in fullscreen mode.
See also:
2024-7-12
GEnum gdk:surface-edge
Declaration:
(gobject:define-genum "GdkSurfaceEdge" surface-edge
  (:export t
   :type-initializer "gdk_surface_edge_get_type")
  (:north-west 0)
  (:north 1)
  (:north-east 2)
  (:west 3)
  (:east 4)
  (:south-west 5)
  (:south 6)
  (:south-east 7))  
Values:
:north-west
The top left corner.
:north
The top edge.
:north-east
The top right corner.
:west
The left edge.
:east
The right edge.
:south-west
The lower left corner.
:south
The lower edge.
:south-east
The lower right corner.
Details:
Determines a surface edge or corner.
See also:
2024-7-12
GEnum gdk:titlebar-gesture
Declaration:
(gobject:define-genum "GdkTitlebarGesture" titlebar-gesture
  (:export t
   :type-initializer "gdk_titlebar_gesture_get_type")
  (:double-click 0)
  (:right-click 1)
  (:middle-click 2))  
Values:
:double-click
No description available.
:right-click
No description available.
:middle-click
No description available.
Details:
The kind of title bar gesture to emit with the gdk:toplevel-titlebar-gesture function.

Since 4.4
See also:
2024-7-12
Interface gdk:toplevel
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
decorated
The decorated property of type :boolean (Read / Write)
Whether the toplevel is decorated.
Default value: false
deletable
The deletable property of type :boolean (Read / Write)
Whether the toplevel is deletable.
Default value: false
fullscreen-mode
The fullscreen-mode property of type gdk:fullscreen-mode (Read / Write)
The fullscreen mode of the toplevel.
Default value: :on-current-monitor
icon-list
The icon-list property of type :pointer (Read / Write)
The list of icon textures.
modal
The modal property of type :boolean (Read / Write)
Whether the toplevel is modal.
Default value: false
shortcuts-inhibited
The shortcuts-inhibited property of type :boolean (Read / Write)
Whether keyboard shortcuts are inhibited.
Default value: false
startup-id
The startup-id property of type :string (Read / Write)
The startup ID of the surface.
Default value: nil
state
The state property of type gdk:toplevel-state (Read)
The state of the toplevel.
title
The title property of type :string (Read / Write)
The title of the surface.
Default value: nil
transient-for
The transient-for property of type gdk:surface (Read / Write)
The transient parent of the surface.
Slot Access Functions:
Details:
The gdk:toplevel object is a freestanding toplevel surface. The gdk:toplevel interface provides useful APIs for interacting with the windowing system, such as controlling maximization and size of the surface, setting icons and transient parents for dialogs.
Signal Details:
The "compute-size" signal
lambda (toplevel size)    :run-last      
toplevel
The gdk:toplevel object.
size
The gdk:toplevel-size instance.
Compute the desired size of the toplevel, given the information passed via the gdk:toplevel-size instance. It will normally be emitted during or after the gdk:toplevel-present function, depending on the configuration received by the windowing system. It may also be emitted at any other point in time, in response to the windowing system spontaneously changing the configuration. It is the responsibility of the toplevel user to handle this signal. Failing to do so will result in an arbitrary size being used as a result.
See also:
2014-4-7
Accessor gdk:toplevel-decorated (object)
Syntax:
(gdk:toplevel-decorated object) => decorated
(setf (gdk:toplevel-decorated object) decorated)
Arguments:
object -- a gdk:toplevel object
decorated -- a boolean whether to request decorations
Details:
Accessor of the decorated slot of the gdk:toplevel class. Setting decorated to false hints the desktop environment that the surface has its own, client-side decorations and does not need to have window decorations added.
See also:
#2023-4-8
Accessor gdk:toplevel-deletable (object)
Syntax:
(gdk:toplevel-deletable object) => deletable
(setf (gdk:toplevel-deletable object) deletable)
Arguments:
object -- a gdk:toplevel object
deletable -- a boolean whether to request a delete button
Details:
Accessor of the deletable slot of the gdk:toplevel class. Setting deletable to true hints the desktop environment that it should offer the user a way to close the surface.
See also:
#2023-4-8
Accessor gdk:toplevel-fullscreen-mode (object)
Syntax:
(gdk:toplevel-fullscreen-mode object) => mode
(setf (gdk:toplevel-fullscreen-mode object) mode)
Arguments:
object -- a gdk:toplevel object
mode -- a boolean with the fullscreen mode of the surface
Details:
Accessor of the fullscreen-mode slot of the gdk:toplevel class.
See also:
#2023-4-8
Accessor gdk:toplevel-icon-list (object)
Syntax:
(gdk:toplevel-icon-list object) => surfaces
(setf (gdk:toplevel-icon-list object) surfaces)
Arguments:
object -- a gdk:toplevel object
surfaces -- a list of textures to use as icon, of different sizes
Details:
Accessor of the icon-list slot of the gdk:toplevel class. The (setf gdk:toplevel-icon-list) function sets a list of icons for the surface. One of these will be used to represent the surface in iconic form. The icon may be shown in window lists or task bars. Which icon size is shown depends on the window manager. The window manager can scale the icon but setting several size icons can give better image quality.

Note that some platforms do not support surface icons.
See also:
#2023-4-8
Accessor gdk:toplevel-modal (object)
Syntax:
(gdk:toplevel-modal object) => modal
(setf (gdk:toplevel-modal object) modal)
Arguments:
object -- a gdk:toplevel object
modal -- true if the surface is modal, false otherwise
Details:
Accessor of the modal slot of the gdk:toplevel class. The application can use this hint to tell the window manager that a certain surface has modal behaviour. The window manager can use this information to handle modal surfaces in a special way.

You should only use this on surfaces for which you have previously called the gdk:toplevel-transient-for function.
See also:
#2023-4-8
Accessor gdk:toplevel-shortcuts-inhibited (object)
Syntax:
(gdk:toplevel-shortcuts-inhibited object) => inhibited
(setf (gdk:toplevel-shortcuts-inhibited object) inhibited)
Arguments:
object -- a gdk:toplevel object
inhibited -- a boolean whether keyboard shortcuts are inhibited
Details:
Accessor of the shortcuts-inhibited slot of the gdk:toplevel class.
See also:
#2023-4-8
Accessor gdk:toplevel-startup-id (object)
Syntax:
(gdk:toplevel-startup-id object) => startup-id
(setf (gdk:toplevel-startup-id object) startup-id)
Arguments:
object -- a gdk:toplevel object
startup-id -- a string with startup-notification identifier
Details:
Accessor of the startup-id slot of the gdk:toplevel class. When using GTK, typically you should use the gtk:window-startup-id function instead of this low-level function.
See also:
#2023-4-8
Accessor gdk:toplevel-state (object)
Syntax:
(gdk:toplevel-state object) => state
(setf (gdk:toplevel-state object) state)
Arguments:
object -- a gdk:toplevel object
state -- a gdk:toplevel-state value
Details:
Accessor of the state slot of the gdk:toplevel class. Gets the bitwise OR of the currently active surface state flags, from the gdk:toplevel-state enumeration.
See also:
#2024-4-7
Accessor gdk:toplevel-title (object)
Syntax:
(gdk:toplevel-title object) => title
(setf (gdk:toplevel-title object) title)
Arguments:
object -- a gdk:toplevel object
state -- a string with the title of surface
Details:
Accessor of the state slot of the gdk:toplevel class. Sets the title of a toplevel surface, to be displayed in the titlebar, in lists of windows, etc.
See also:
#2023-4-8
Accessor gdk:toplevel-transient-for (object)
Syntax:
(gdk:toplevel-transient-for object) => parent
(setf (gdk:toplevel-transient-for object) parent)
Arguments:
object -- a gdk:toplevel object
parent -- a toplevel gdk:surface object
Details:
Accessor of the transient-for slot of the gdk:toplevel class. Indicates to the window manager that surface is a transient dialog associated with the application surface parent. This allows the window manager to do things like center surface on parent and keep surface above parent.

See the gtk:window-transient-for function if you are using gtk:window or gtk:dialog widgets.
See also:
#2023-4-8
Function gdk:toplevel-present (toplevel layout)
Arguments:
toplevel -- a gdk:toplevel object to show
layout -- a gdk:toplevel-layout instance used to layout
Details:
Present toplevel after having processed the gtk:toplevel-layout rules. If the toplevel was previously not showing, it will be showed, otherwise it will change layout according to layout.

GDK may emit the "compute-size" signal to let the user of this toplevel compute the preferred size of the toplevel surface. See "compute-size" signal for details.

Presenting is asynchronous and the specified layout parameters are not guaranteed to be respected.
See also:
#2023-8-1
Function gdk:toplevel-minimize (toplevel)
Arguments:
toplevel -- a gdk:toplevel object
Returns:
True if the surface was minimized.
Details:
Asks to minimize the toplevel. The windowing system may choose to ignore the request.
See also:
#2023-8-1
Function gdk:toplevel-lower (toplevel)
Arguments:
toplevel -- a gdk:toplevel object
Returns:
True if the surface was lowered.
Details:
Asks to lower the toplevel below other windows. The windowing system may choose to ignore the request.
See also:
#2023-8-1
Function gdk:toplevel-focus (toplevel timestamp)
Arguments:
toplevel -- a gdk:toplevel object
timestamp -- an unsigned integer with the timestamp of the event triggering the surface focus
Details:
Sets keyboard focus to surface . In most cases, the gtk:window-present-with-time function should be used on a gtk:window widget, rather than calling this function.
See also:
#2023-8-1
Function gdk:toplevel-show-window-menu (toplevel event)
Arguments:
toplevel -- a gdk:toplevel object
event -- a gdk:event instance to show the menu for
Returns:
True if the window menu was shown and false otherwise.
Details:
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.
See also:
#2023-8-1
Function gdk:toplevel-supports-edge-constraints (toplevel)
Arguments:
toplevel -- a gdk:toplevel object
Returns:
True if the desktop environment supports tiled window states.
Details:
Returns whether the desktop environment supports tiled window states.
See also:
#2023-8-1
Function gdk:toplevel-inhibit-system-shortcuts (toplevel event)
Arguments:
toplevel -- a gdk:toplevel object requesting system keyboard shortcuts
event -- a gdk:event instance that is triggering the inhibit request, or nil if none is available
Details:
Requests that the toplevel inhibit the system shortcuts, asking the desktop environment/windowing system to let all keyboard events reach the surface, as long as it is focused, instead of triggering system actions.

If granted, the rerouting remains active until the default shortcuts processing is restored with the gdk:toplevel-restore-system-shortcuts function, or the request is revoked by the desktop environment, windowing system or the user.

A typical use case for this API is remote desktop or virtual machine viewers which need to inhibit the default system keyboard shortcuts so that the remote session or virtual host gets those instead of the local environment.

The windowing system or desktop environment may ask the user to grant or deny the request or even choose to ignore the request entirely.

The caller can be notified whenever the request is granted or revoked by listening to the shortcuts-inhibited property.
See also:
#2023-8-1
Function gdk:toplevel-restore-system-shortcuts (toplevel)
Arguments:
toplevel -- a gdk:toplevel object
Details:
Restore default system keyboard shortcuts which were previously requested to be inhibited by the gdk:toplevel-inhibit-system-shortcuts function.
See also:
#2023-8-1
Function gdk:toplevel-begin-resize (toplevel edge device button x y timestamp)
Arguments:
toplevel -- a gdk:toplevel object
edge -- a gdk:surface-edge value with the edge or corner from which the drag is started
device -- a gdk:device object used for the operation
button -- an integer with the button being used to drag, or 0 for a keyboard-initiated drag
x -- a double float with the surface x coordinate of mouse click that began the drag
y -- a double float with the surface y coordinate of mouse click that began the drag
timestamp -- an unsigned integer with the timestamp of mouse click that began the drag, use the gdk:event-time function.
Details:
Begins an interactive resize operation, for a toplevel surface. You might use this function to implement a window resize grip.
See also:
#2023-8-1
Function gdk:toplevel-begin-move (toplevel device button x y timestamp)
Arguments:
toplevel -- a gdk:toplevel object
device -- a gdk:device object used for the operation
button -- an integer with the button being used to drag, or 0 for a keyboard-initiated drag
x -- a double float with the surface x coordinate of mouse click that began the drag
y -- a double float with the surface y coordinate of mouse click that began the drag
timestamp -- an unsigned integer with the timestamp of mouse click that began the drag
Details:
Begins an interactive move operation, for a toplevel surface. You might use this function to implement draggable titlebars.
See also:
#2023-8-1
Function gdk:toplevel-titlebar-gesture (toplevel gesture)
Arguments:
toplevel -- a gdk:toplevel object
gesture -- a gdk:titlebar-gesture value
Returns:
The boolean value.
Details:
No description available.

Since 4.4
See also:
#2023-8-1

GdkPopupLayout

GFlags gdk:anchor-hints
Declaration:
(gobject:define-gflags "GdkAnchorHints" anchor-hints
  (:export t
   :type-initializer "gdk_anchor_hints_get_type")
  (:flip-x #.(ash 1 0))
  (:flip-y #.(ash 1 1))
  (:slide-x #.(ash 1 2))
  (:slide-y #.(ash 1 3))
  (:resize-x #.(ash 1 4))
  (:resize-y #.(ash 1 5))
  (:flip #.(+ (ash 1 0) (ash 1 1)))
  (:slide #.(+ (ash 1 2) (ash 1 3)))
  (:resize #.(+ (ash 1 4) (ash 1 5))))  
Values:
:flip-x
Allow flipping anchors horizontally.
:flip-y
Allow flipping anchors vertically.
:slide-x
Allow sliding surface horizontally.
:slide-y
Allow sliding surface vertically.
:resize-x
Allow resizing surface horizontally.
:resize-y
Allow resizing surface vertically.
:flip
Allow flipping anchors on both axes.
:slide
Allow sliding surface on both axes.
:resize
Allow resizing surface on both axes.
Details:
Positioning hints for aligning a surface relative to a rectangle. These hints determine how the surface should be positioned in the case that the surface would fall off-screen if placed in its ideal position.

For example, the :flip-x value will replace the :north-west gravity with the :north-east gravity and vice versa if the surface extends beyond the left or right edges of the monitor.

If the :slide-x value is set, the surface can be shifted horizontally to fit on-screen. If the :resize-x value is set, the surface can be shrunken horizontally to fit.

In general, when multiple flags are set, flipping should take precedence over sliding, which should take precedence over resizing.
See also:
2024-2-17
GBoxed gdk:popup-layout
Returned by:
Details:
Popups are positioned relative to their parent surface. The gdk:popup-layout structure contains information that is necessary to do so. The positioning requires a negotiation with the windowing system, since it depends on external constraints, such as the position of the parent surface, and the screen dimensions.

The basic ingredients are a rectangle on the parent surface, and the anchor on both that rectangle and the popup. The anchors specify a side or corner to place next to each other.

Figure: Popup anchors

For cases where placing the anchors next to each other would make the popup extend offscreen, the layout includes some hints for how to resolve this problem. The hints may suggest to flip the anchor position to the other side, or to 'slide' the popup along a side, or to resize it. These hints may be combined.

Figure: Flipping popups

Figure: Sliding popups

Ultimatively, it is up to the windowing system to determine the position and size of the popup. You can learn about the result by calling the gdk:popup-position-x, gdk:popup-position-y, gdk:popup-rect-anchor and gdk:popup-surface-anchor functions after the popup has been presented. This can be used to adjust the rendering. For example, the gtk:popover object changes its arrow position accordingly. But you have to be careful avoid changing the size of the popover, or it has to be presented again.
See also:
2024-2-17
Function gdk:popup-layout-new (rect rect-anchor surface-anchor)
Arguments:
rect -- a gdk:rectangle instance with the anchor rectangle to align surface with
rect-anchor -- a gdk:gravity value with the point on rect to align with the anchor point of the surface
surface-anchor -- a gdk:gravity value with the point on surface to align with the anchor point of rect
Returns:
The newly created gdk:popup-layout instance.
Details:
Create a popup layout description. Used together with the gdk:popup-present function to describe how a popup surface should be placed and behave on-screen.

The rectangle is relative to the top-left corner of the parent of the surface. The rect-anchor and surface-anchor values determine anchor points on the rectangle and surface to pin together.

The position of the anchor point of the rectangle can optionally be offset using the gdk:popup-layout-offset function, which is equivalent to offsetting the position of surface.
See also:
2024-2-17
Function gdk:popup-layout-copy (layout)
Arguments:
layout -- a gdk:popup-layout instance
Returns:
The gdk:popup-layout instance with the copy of layout.
Details:
Create a new popup layout and copy the contents of layout into it.
See also:
2024-2-17
Function gdk:popup-layout-equal (layout1 layout2)
Arguments:
layout1 -- a gdk:popup-layout instance
layout2 -- a gdk:popup-layout instance
Returns:
True if layout1 and layout2 have identical layout properties, otherwise false.
Details:
Check whether layout1 and layout2 have identical layout properties.
See also:
2024-2-17
Function gdk:popup-layout-anchor-rect (layout)
Syntax:
(gdk:popup-layout-anchor-rect layout) => rect
(setf (gdk:popup-layout-anchor-rect layout) rect)
Arguments:
layout -- a gdk:popup-layout instance
rect -- an anchor gdk:rectangle instance
Details:
The gdk:popup-layout-anchor-rect function gets the anchor rectangle. The (setf gdk:popup-layout-anchor-rect) function sets the anchor rectangle.
See also:
2024-2-17
Function gdk:popup-layout-rect-anchor (layout)
Syntax:
(gdk:popup-layout-rect-anchor layout) => gravity
(setf (gdk:popup-layout-rect-anchor layout) gravity)
Arguments:
layout -- a gdk:popup-layout instance
gravity -- a gdk:gravity value with the anchor on the anchor rectangle
Details:
The gdk:popup-layout-rect-anchor function returns the anchor position on the anchor rectangle. The (setf gdk:popup-layout-rect-anchor) function sets the anchor on the anchor rectangle.
See also:
2024-2-17
Function gdk:popup-layout-surface-anchor (layout)
Syntax:
(gdk:popup-layout-surface-anchor layout) => gravity
(setf (gdk:popup-layout-surface-anchor layout) gravity)
Arguments:
layout -- a gdk:popup-layout instance
gravity -- a gdk:gravity value with the anchor on the popup surface
Details:
The gdk:popup-layout-surface-anchor function returns the anchor position on the popup surface. The (setf gdk:popup-layout-surface-anchor) function sets the anchor on the popup surface.
See also:
2024-2-17
Function gdk:popup-layout-anchor-hints (layout)
Syntax:
(gdk:popup-layout-anchor-hints layout) => hints
(setf (gdk:popup-layout-anchor-hints layout) hints)
Arguments:
layout -- a gdk:popup-layout instance
hints -- a gdk:anchor-hints value
Details:
The gdk:popup-layout-anchor-hints function gets the anchor hints. The (setf gdk:popup-layout-anchor-hints) function sets new anchor hints.

The anchor hints determines how surface will be moved if the anchor points cause it to move off-screen. For example, the :flip-x value will replace the :north-west gravity with the :north-east gravity and vice versa if surface extends beyond the left or right edges of the monitor.
See also:
2024-2-17
Function gdk:popup-layout-offset (layout)
Syntax:
(gdk:popup-layout-offset layout) => dx, dy
(setf (gdk:popup-layout-offset layout) (list dx dy))
Arguments:
layout -- a gdk:popup-layout instance
dx -- an integer with the delta x coordinate
dx -- an integer with the delta y coordinate
Details:
The gdk:popup-layout-offset function retrieves the offset for the anchor rectangle. The (setf gdk:popup-layout-offset) function offset the position of the anchor rectangle with the given delta.
See also:
2024-2-17
Function gdk:popup-layout-shadow-width (layout)
Syntax:
(gdk:popup-layout-shadow-width layout) => left, right, top, bottom
(setf (gdk:popup-layout-shadow-width layout) (list left right top bottom))
Arguments:
layout -- a gdk:popup-layout instance
left -- an integer with the left shadow width
right -- an integer with the right shadow width
top -- an integer with the top shadow width
bottom -- an integer with the bottom shadow width
Details:
The gdk:popup-layout-shadow-width function obtains the shadow widths of the popup layout. The (setf gdk:popup-layout-shadow-width) function sets the shadow width.

The shadow width corresponds to the part of the computed surface size that would consist of the shadow margin surrounding the window, would there be any.

Since 4.2
See also:
2024-2-17

GdkPopup

Interface gdk:popup
Superclasses:
gdk:surface, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
autohide
The autohide property of type :boolean (Read / Write / Construct only)
Whether to hide on outside clicks.
Default value: false
parent
The parent property of type gdk:surface (Read / Write / Construct only)
The parent surface.
Details:
A gdk:popup object is a surface that is attached to another surface, called its "parent", and is positioned relative to it. gdk:popup objects are typically used to implement menus and similar popups. They can be modal, which is indicated by the autohide property.
See also:
#2023-4-9
Accessor gdk:popup-autohide (object)
Syntax:
(gdk:popup-autohide object) => autohide
(setf (gdk:popup-autohide object) autohide)
Arguments:
object -- a gdk:popup object
autohide -- True if popup will autohide.
Details:
Accessor of the autohide slot of the gdk:popup class. The gdk:popup-autohide function returns whether the popup is set to hide on outside clicks.
See also:
#2023-4-9
Accessor gdk:popup-parent (object)
Syntax:
(gdk:popup-parent object) => parent
(setf (gdk:popup-parent object) parent)
Arguments:
object -- a gdk:popup object
parent -- a gdk:surface parent surface
Details:
Accessor of the parent slot of the gdk:popup class. The gdk:popup-parent function returns the parent surface of a popup.
See also:
#2023-4-9
Function gdk:popup-present (popup width height layout)
Arguments:
popup -- a gdk:popup object to show
width -- an integer with the unconstrained popup width to layout
height -- an integer with the unconstrained popup height to layout
layout -- a gdk:popup-layout object used to layout
Returns:
False if it failed to be presented, otherwise true.
Details:
Present popup after having processed the gdk:popup-layout rules. If the popup was previously now showing, it will be showed, otherwise it will change position according to layout.

After calling this function, the result should be handled in response to the "layout" signal being emitted. The resulting popup position can be queried using the gdk:popup-position-x, gdk:popup-position-y functions, and the resulting size will be sent as parameters in the layout signal. Use the gdk:popup-rect-anchor and gdk:popup-surface-anchor function to get the resulting anchors.

Presenting may fail, for example if the popup is set to autohide and is immediately hidden upon being presented. If presenting failed, the "layout" signal will not me emitted.
See also:
#2023-4-10
Function gdk:popup-surface-anchor (popup)
Arguments:
popup -- a gdk:popup object
Returns:
The gdk:gravity value with the current anchor value of popup.
Details:
Gets the current popup surface anchor. The value returned may change after calling the gdk:popup-present function, or after the "layout" signal is emitted.
See also:
#2023-4-10
Function gdk:popup-rect-anchor (popup)
Arguments:
popup -- a gdk:popup object
Returns:
The gdk:gravity value with the current rectangle anchor value of popup.
Details:
Gets the current popup surface anchor. The value returned may change after calling the gdk:popup-present function, or after the "layout" signal is emitted.
See also:
#2023-4-10
Function gdk:popup-position-x (popup)
Arguments:
popup -- a gdk:popup object
Returns:
The integer with the x coordinate of popup position.
Details:
Obtains the position of the popup relative to its parent.
See also:
#2023-4-10
Function gdk:popup-position-y (popup)
Arguments:
popup -- a gdk:popup object
Returns:
The integer with the y coordinate of popup position.
Details:
Obtains the position of the popup relative to its parent.
See also:
#2023-4-10

Draw contexts

GdkDrawContext

Class gdk:draw-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
display
The display property of type gdk:display (Read / Write / Construct Only)
The display used to create the draw context.
surface
The surface property of type gdk:surface (Read / Write / Construct Only)
The surface the draw context is bound to.
Slot Access Functions:
Details:
The gdk:draw-context object is the base object used by contexts implementing different rendering methods, such as the gdk:gl-context context. It provides shared functionality between those contexts. You will always interact with one of those subclasses.

A gdk:draw-context object is always associated with a single toplevel surface.
See also:
2024-11-29
Accessor gdk:draw-context-display (object)
Syntax:
(gdk:draw-context-display object) => display
Arguments:
object -- a gdk:draw-context object
display -- a gdk:display object or nil
Details:
Accessor of the display slot of the gdk:draw-context class. The gdk:draw-context-display function retrieves the display the draw context is created for.
See also:
2024-11-29
Accessor gdk:draw-context-surface (object)
Syntax:
(gdk:draw-context-surface object) => surface
Arguments:
object -- a gdk:draw-context object
surface -- a gdk:surface object or nil
Details:
Accessor of the surface slot of the gdk:draw-context class. The gdk:draw-context-surface function retrieves the surface used by the draw context.
See also:
2024-11-29
Function gdk:draw-context-begin-frame (context region)
Arguments:
context -- a gdk:draw-context object used to draw the frame
region -- a cairo:region-t instance with the minimum region that should be drawn
Details:
Indicates that you are beginning the process of redrawing region on the surface of context. Calling this function begins a drawing operation using the context on the surface that the context was created from. The actual requirements and guarantees for the drawing operation vary for different implementations of drawing, so a gdk:cairo-context and a gdk:gl-context object need to be treated differently.

A call to this function is a requirement for drawing and must be followed by a call to the gdk:draw-context-end-frame function, which will complete the drawing operation and ensure the contents become visible on screen.

Note that the region passed to this function is the minimum region that needs to be drawn and depending on implementation, windowing system and hardware in use, it might be necessary to draw a larger region. Drawing implementation must use the gdk:draw-context-frame-region function to query the region that must be drawn.

When using GTK, the widget system automatically places calls to the gdk:draw-context-begin-frame and gdk:draw-context-end-frame functions via the use of gsk:renderer objects, so application code does not need to call these functions explicitly.
Warning:
This function is deprecated since 4.16. Drawing directly to the surface is no longer recommended. Use the gsk:render-node and gsk:renderer API.
See also:
#2024-11-7
Function gdk:draw-context-end-frame (context)
Arguments:
context -- a gdk:draw-context object
Details:
Ends a drawing operation started with the gdk:draw-context-begin-frame function and makes the drawing available on screen. See that function for more details about drawing.

When using a gdk:gl-context object, this function may call the glFlush() function implicitly before returning. It is not recommended to call the glFlush() function explicitly before calling this function.
Warning:
This function is deprecated since 4.16. Drawing directly to the surface is no longer recommended. Use the gsk:render-node and gsk:renderer API.
See also:
#2024-11-7
Function gdk:draw-context-is-in-frame (context)
Arguments:
context -- a gdk:draw-context object
Returns:
True if the draw context is between the gdk:draw-context-begin-frame and gdk:draw-context-end-frame function calls.
Details:
Returns true if context is in the process of drawing to its surface after a call to the gdk:draw-context-begin-frame function and not yet having called the gdk:draw-context-end-frame function. In this situation, drawing commands may be effecting the contents of a surface of the context.
Warning:
This function is deprecated since 4.16. Drawing directly to the surface is no longer recommended. Use the gsk:render-node and gsk:renderer API.
See also:
#2024-11-7
Function gdk:draw-context-frame-region (context)
Arguments:
context -- a gdk:draw-context object
Returns:
The cairo:region-t instance or cffi:null-pointer if not drawing a frame.
Details:
Retrieves the region that is currently in the process of being repainted.

After a call to the gdk:draw-context-begin-frame function this function will return a union of the region passed to that function and the area of the surface that the draw context determined needs to be repainted.

If context is not in between calls to the gdk:draw-context-begin-frame and gdk:draw-context-end-frame functions, cffi:null-pointer will be returned.
Warning:
This function is deprecated since 4.16. Drawing directly to the surface is no longer recommended. Use the gsk:render-node and gsk:renderer API.
See also:
2024-12-29

GdkGLContext

GFlags gdk:gl-api
Declaration:
(gobject:define-gflags "GdkGLAPI" gl-api
  (:export t
   :type-initializer "gdk_gl_api_get_type")
  (:none 0)
  (:gl #.(ash 1 0))
  (:gles #.(ash 1 1)))  
Values:
:none
No API.
:gl
The OpenGL API.
:gles
The OpenGL ES API.
Details:
The list of the different APIs that a gdk:gl-context object can potentially support. Since 4.6
See also:
#2023-8-3
Class gdk:gl-context
Superclasses:
gdk:draw-context, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
allowed-apis
The allowed-apis property of type gdk:gl-api (Read / Write)
The allowed APIs. Since 4.6
Default value: '(:gl :gles)
api
The api property of type gdk:gl-api (Read)
The API currently in use. Since 4.6
Default value: :none
shared-context
The shared-context property of type gdk:gl-context (Read / Write / Construct only)
The GL context that this context is sharing data with, or nil. Deprecated since 4.4
Slot Access Functions:
Details:
The gdk:gl-context object is an object representing the platform specific OpenGL draw context. A gdk:gl-context object is created for a gdk:surface object using the gdk:surface-create-gl-context function, and the context will match the the characteristics of the surface.

A gdk:gl-context object is not tied to any particular normal framebuffer. For instance, it cannot draw to the gdk:surface back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use the gdk:cairo-draw-from-gl function 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 the gdk:gl-context object is platform specific, context creation can fail, returning a NULL context.

A gdk:gl-context object 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 gdk:gl-context object you need a gdk:surface object, which you typically get during the realize call of a widget.

A gdk:gl-context object is not realized until either the gdk:gl-context-make-current function, or until it is realized using the gdk:gl-context-realize function. 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 the gdk:surface-create-gl-context function by calling the gdk:gl-context-realize function. If the realization fails you have the option to change the settings of the gdk:gl-context object and try again.

Using a GdkGLContext
You will need to make the gdk:gl-ontext object 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:
(gdk:gl-context-make-current context)  
You can now perform your drawing using OpenGL commands.

You can check which gdk:gl-context object is the current one by using the gdk:gl-context-current function. You can also unset any gdk:gl-context object that is currently set by calling the gdk:gl-context-clear-current function.
See also:
#2023-8-3
Accessor gdk:gl-context-allowed-apis (object)
Syntax:
(gdk:gl-context-allowed-apis object) => apis
(setf (gdk:gl-context-allowed-apis object) apis)
Arguments:
object -- a gdk:gl-context object
apis -- a gdk:gl-apis value
Details:
Accessor of the allowed-apis slot of the gdk:gl-context class. The gdk:gl-context-allowed-apis function gets the allowed APIs. The (setf gdk:gl-context-allowed-apis) function sets the allowed APIs. When the gdk:gl-context-realize function is called, only the allowed APIs will be tried. If you set this to :none, realizing will always fail.

If you set it on a realized context, the property will not have any effect. It is only relevant during the gdk:gl-context-realize function.

By default, all APIs are allowed.

Since 4.6
See also:
#2023-8-4
Accessor gdk:gl-context-api (object)
Syntax:
(gdk:gl-context-api object) => api
Arguments:
object -- a gdk:gl-context object
api -- a gdk:gl-api value
Details:
Accessor of the api slot of the gdk:gl-context class. The gdk:gl-context-api function gets the API currently in use. If the renderer has not been realized yet, :none is returned.

Since 4.6
See also:
#2023-8-4
Accessor gdk:gl-context-shared-context (object)
Syntax:
(gdk:gl-context-shared-context object) => context
Arguments:
object -- a gdk:gl-context object
context -- a gdk:gl-context object or nil
Details:
Accessor of the shared-context slot of the gdk:gl-context class. The gdk:gl-context-shared-context function retrieves the GL context that this context share data with.

Deprecated since 4.6
See also:
#2023-8-4
Function gdk:gl-context-display (context)
Arguments:
context -- a gdk:gl-context object
Returns:
The gdk:display object or nil.
Details:
Retrieves the display the GL context is created for.
See also:
#2023-8-3
Function gdk:gl-context-surface (context)
Arguments:
context -- a gdk:gl-context object
Returns:
The gdk:surface object or nil.
Details:
Retrieves the surface used by the GL context.
See also:
#2023-8-3
Function gdk:gl-context-version (context)
Arguments:
context -- a gdk:gl-context object
Returns:
major - an integer with the major version
minor - an integer with the minor version
Details:
Retrieves the OpenGL version of the GL context. The GL context must be realized prior to calling this function.
See also:
#2023-8-3
Function gdk:gl-context-debug-enabled (context)
Syntax:
(gdk:gl-context-debug-enabled object) => enabled
(setf gdk:gl-context-debug-enabled object) enabled)
Arguments:
context -- a gdk:gl-context object
enabled -- a boolean whether debugging is enabled
Details:
The gdk:gl-context-debug-enabled function retrieves whether debugging is enabled. The (setf gdk:gl-context-debug-enabled) function sets whether the GL context should perform extra validations and run time checking. This is useful during development, but has additional overhead.

The gdk:gl-context object must not be realized or made current prior to calling this function.
See also:
#2023-8-3
Function gdk:gl-context-forward-compatible (context)
Syntax:
(gdk:gl-context-forward-compatible object) => setting
(setf gdk:gl-context-forward-compatible object) setting)
Arguments:
context -- a gdk:gl-context object
setting -- a boolean whether context is forward compatible
Details:
The gdk:gl-context-forward-compatible function returns whether the GL context should be forward compatible. The (setf gdk:gl-context-forward-compatible) function sets whether the GL context should be forward compatible.

Forward compatible GL contexts must not support OpenGL functionality that has been marked as deprecated in the requested version. Non-forward compatible GL contexts, on the other hand, must support both deprecated and non deprecated functionality.

The gdk:gl-context object must not be realized or made current prior to calling this function.
See also:
#2023-8-3
Function gdk:gl-context-use-es (context)
Syntax:
(gdk:gl-context-uses-es object) => setting
(setf gdk:gl-context-use-es object) setting)
Arguments:
context -- a gdk:gl-context object
setting -- an integer whether the context uses OpenGL instead of OpenGL, or -1 to allow auto-detection
Details:
The gdk:gl-context-uses-es function checks whether the context is using an OpenGL or OpenGL ES profile. The gdk:gl-context-uses-es function requests that GDK create an OpenGL ES context instead of an OpenGL one, if the platform and windowing system allows it. The context must not have been realized.

By default, GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the context is realized.

You should check the return value of the gdk:gl-context-use-es function after calling the gdk:gl-context-realize function to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders.
See also:
#2023-8-3
Function gdk:gl-context-is-legacy (context)
Arguments:
context -- a gdk:gl-context object
Returns:
True if the GL context is in legacy mode.
Details:
Whether the GL context is in legacy mode or not. The gdk:gl-context object 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.
See also:
#2023-8-3
Function gdk:gl-context-realize (context)
Arguments:
context -- a gdk:gl-context object
Returns:
True if the OpenGL context is realized.
Details:
Realizes the given OpenGL context. It is safe to call this function on a realized OpenGL context.
See also:
#2024-11-21
Function gdk:gl-context-make-current (context)
Arguments:
context -- a gdk:gl-context object
Details:
Makes the GL context the current one.
See also:
#2023-8-3
Function gdk:gl-context-current ()
Returns:
The current gdk:gl-context object, or nil.
Details:
Retrieves the current GL context.
See also:
#2023-8-3
Function gdk:gl-context-clear-current ()
Details:
Clears the current GL context. Any OpenGL call after this function returns will be ignored until the gdk:gl-context-make-current function is called.
See also:
#2023-8-3

GdkCairoContext

Class gdk:cairo-context
Superclasses:
gdk:draw-context, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:cairo-context object is an object representing the platform specific draw context. The gdk:cairo-context objects are created for a gdk:display object using the gdk:surface-create-cairo-context function, and the context can then be used to draw on that gdk:surface object.
See also:
2023-4-7
Function gdk:cairo-context-cairo-create (context)
Arguments:
context -- a gdk:cairo-context object that is currently drawing
Returns:
The cairo:context-t instance with the Cairo context to be used to draw the contents of the gdk:surface object. NULL is returned when context is not drawing.
Details:
Retrieves a Cairo context to be used to draw on the gdk:surface object of context. A call to the gdk:draw-context-begin-frame function with this context must have been done or this function will return NULL. The returned context is guaranteed to be valid until the gdk:draw-context-end-frame function is called.
See also:
2024-7-12

Clipboard, Drag and Drop

Content Formats

GBoxed gdk:content-formats
Returned by:
Details:
The gdk:content-formats structure is used to advertise and negotiate the format of content. You will encounter gdk:content-formats instances when interacting with objects controlling operations that pass data between different widgets, window or application, like gdk:drag, gdk:drop, gdk:clipboard or gdk:content-provider objects.

GDK supports content in two forms: GType and mime type. Using GTypes is meant only for in-process content transfers. Mime types are meant to be used for data passing both in-process and out-of-process. The details of how data is passed is described in the documentation of the actual implementations. To transform between the two forms, the gdk:content-serializer and gdk:content-deserializer objects are used.

A gdk:content-formats instance describes a set of possible formats content can be exchanged in. It is assumed that this set is ordered. GTypes are more important than mime types. Order between different GTypes or mime types is the order they were added in, most important first. Functions that care about order, such as the gdk:content-formats-union function, will describe in their documentation how they interpret that order, though in general the order of the first argument is considered the primary order of the result, followed by the order of further arguments.

For debugging purposes, the gdk:content-formats-to-string function exists. It will print a comma-separated list of formats from most important to least important.

The gdk:content-formats structure is an immutable structure. After creation, you cannot change the types it represents. Instead, new gdk:content-formats instances have to be created. The gdk:content-formats-builder structure is meant to help in this endeavor.
See also:
2023-11-5
Function gdk:content-formats-new (mime-types)
Arguments:
mime-types -- a list of strings with the mime types
Returns:
The new gdk:content-formats instance.
Details:
Creates a new gdk:content-formats instance from a list of mime types. The mime types must be valid and different from each other or the behavior of the return value is undefined. If you cannot guarantee this, use the gdk:content-formats-builder object instead.
See also:
gdk:content-formats
gdk:content-formats-builder
#2023-8-4
Function gdk:content-formats-new-for-gtype (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
The new gdk:content-formats instance.
Details:
Creates a new gdk:content-formats instance for a given gtype.
See also:
#2023-8-4
Function gdk:content-formats-to-string (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The string with the content formats.
Details:
Prints the given formats into a human-readable string.
See also:
#2023-8-4
Function gdk:content-formats-parse (str)
Arguments:
str -- a string to parse
Returns:
The gdk:content-formats instance with the content formats if str is valid.
Details:
Parses the given str into a gdk:content-formats instance and returns the formats. Strings printed via the gdk:content-formats-to-string function can be read in again successfully using this function.

If str does not describe valid content formats, nil is returned.

Since 4.4
See also:
#2023-4-14
Function gdk:content-formats-gtypes (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The list with the g:type-t type IDs included in formats.
Details:
Gets the g:type-t type IDs included in formats. Note that formats may not contain any g:type-t type IDs, in particular when they are empty. In that case nil will be returned.
See also:
#2023-8-4
Function gdk:content-formats-mime-types (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The list of strings with the mime types included in formats.
Details:
Gets the mime types included in formats. Note that formats may not contain any mime types, in particular when they are empty. In that case nil will be returned.
See also:
#2023-8-4
Function gdk:content-formats-union (first second)
Arguments:
first -- a gdk:content-formats instance to merge into
second -- a gdk:content-formats instance to merge from
Returns:
The new gdk:content-formats instance
Details:
Append all missing types from second to first, in the order they had in second.
See also:
#2023-8-4
Function gdk:content-formats-match (first second)
Arguments:
first -- a gdk:content-formats instance to intersect
second -- a gdk:content-formats instance to intersect with
Returns:
True if a matching format was found.
Details:
Checks if first and second have any matching formats.
See also:
#2023-8-4
Function gdk:content-formats-match-gtype (first second)
Arguments:
first -- a gdk:content-formats instance to intersect
second -- a gdk:content-formats instance to intersect with
Returns:
The first common g:type-t type ID or nil if none.
Details:
Finds the first g:type-t type ID from first that is also contained in second. If no matching g:type-t type ID is found, nil is returned.
See also:
#2023-8-4
Function gdk:content-formats-match-mime-type (first second)
Arguments:
first -- a gdk:content-formats instance to intersect
second -- a gdk:content-formats instance to intersect with
Returns:
The string with the first common mime type type or nil if none.
Details:
Finds the first mime type from first that is also contained in second. If no matching g:type-t type ID is found, nil is returned.
See also:
#2023-8-4
Function gdk:content-formats-contain-gtype (formats gype)
Arguments:
formats -- a gdk:content-formats instance
gtype -- a g:type-t type ID
Returns:
True if given gtype was found.
Details:
Checks if a given gtype is part of the given formats.
See also:
2023-11-5
Function gdk:content-formats-contain-mime-type (formats mime-type)
Arguments:
formats -- a gdk:content-formats instance
mime-type -- a string with the mime type to search for
Returns:
True if given mime-type was found.
Details:
Checks if a given mime type is part of the given formats.
See also:
#2023-11-5
Function gdk:content-formats-union-serialize-gtypes (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The new gdk:content-formats instance.
Details:
Add g:type-t type IDs for the mime types in formats for which serializers are registered.
See also:
#2023-8-4
Function gdk:content-formats-union-deserialize-gtypes (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The new gdk:content-formats instance.
Details:
Add g:type-t type IDs for the mime types in formats for which deserializers are registered.
See also:
#2023-8-4
Function gdk:content-formats-union-serialize-mime-types (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The new gdk:content-formats instance.
Details:
Add mime types for g:type-t type IDs in formats for which serializers are registered.
See also:
#2023-8-4
Function gdk:content-formats-union-deserialize-mime-types (formats)
Arguments:
formats -- a gdk:content-formats instance
Returns:
The new gdk:content-formats instance.
Details:
Add mime types for g:type-t type IDs in formats for which deserializers are registered.
See also:
#2023-8-4

GdkContentProvider

Class gdk:content-provider
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
formats
The formats property of type gdk:content-formats (Read)
The possible formats that the provider can provide its data in.
storable-formats
The storable-formats property of type gdk:content-formats (Read)
The subset of formats that clipboard managers should store the dato of the content provider in.
Details:
A gdk:content-provider object is used to provide content for the clipboard in a number of formats. To create a gdk:content-provider object, use the gdk:content-provider-new-for-value or the gdk:content-provider-new-for-bytes functions.

GDK knows how to handle common text and image formats out-of-the-box. See the gdk:content-serializer and gdk:content-deserializer objects if you want to add support for application specific data formats.
Signal Details:
The "content-changed" signal
lambda (provider)    :run-last      
provider
The gdk:content-provider object.
Emitted whenever the content provided by the provider has changed.
See also:
#2023-8-4
Accessor gdk:content-provider-formats (object)
Syntax:
(gdk:content-provider-formats object) => formats
Arguments:
object -- a gdk:content-provider object
formats -- a gdk:content-formats instance with the formats of the content provider
Details:
Gets the formats that the content provider can provide its current contents in.
See also:
#2023-8-4
Accessor gdk:content-provider-storable-formats (object)
Syntax:
(gdk:content-provider-storable-formats object) => formats
Arguments:
object -- a gdk:content-provider object
formats -- a gdk:content-formats instance with the storable formats of the content provider
Details:
Gets the formats that the content provider suggests other applications to store the data in. An example of such an application would be a clipboard manager. This can be assumed to be a subset of storable-formats.
See also:
#2023-8-4
Function gdk:content-provider-new-for-value (gvalue)
Arguments:
gvalue -- a g:value instance
Returns:
The new gdk:content-provider object.
Details:
Creates a content provider that provides the given gvalue.
See also:
#2023-8-4

GdkContentSerializer

Class gdk:content-serializer
Superclasses:
gio:async-result, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:content-serializer object is used to serialize content for inter-application data transfers. The gdk:content-serializer object transforms an object that is identified by a g:type-t type ID into a serialized form, that is a byte stream, that is identified by a mime type.

GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own serialization functions, use the gdk:content-register-serializer function.

Also see the gdk:content-deserializer object.
See also:
2024-12-2

GdkContentDeserializer

Class gdk:content-deserializer
Superclasses:
gio:async-result, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:content-deserializer object is used to deserialize content received via inter-application data transfers. The gdk:content-deserializer object transforms serialized content that is identified by a mime type into an object identified by a g:type-t type ID.

GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own deserialization functions, use the gdk:content-register-deserializer function.

Also see the gdk:content-serializer object.
See also:
2024-12-2

Clipboards

Class gdk:clipboard
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
content
The content property of type gdk:content-provider (Read)
The content provider or nil if the clipboard is empty or contents are provided otherwise.
display
The display property of type gdk:display (Read / Write / Construct only)
The display that the clipboard belongs to.
formats
The formats property of type gdk:content-formats (Read)
The possible formats that the clipboard can provide its data in.
local
The local property of type :boolean (Read)
True if the contents of the clipboard are owned by this process.
Default value: true
Slot Access Functions:
Details:
The gdk:clipboard object represents data shared between applications or inside an application.

To get a gdk:clipboard object, use the gdk:display-clipboard or gdk:display-primary-clipboard functions. You can find out about the data that is currently available in a clipboard using the gdk:clipboard-formats function.

To make text or image data available in a clipboard, use the gdk:clipboard-set-text or gdk:clipboard-set-texture functions. For other data, you can use the gdk:clipboard-set-content function, which takes a gdk:content-provider object.

To read textual or image data from a clipboard, use the gdk:clipboard-read-text-async or gdk:clipboard-read-texture-async functions.
Signal Details:
The "changed" signal
lambda (clipboard)    :run-last      
clipboard
The gdk:clipboard object on which the signal was emitted.
The signal is emitted when the clipboard changes ownership.
See also:
2023-7-30
Accessor gdk:clipboard-content (object)
Syntax:
(gdk:clipboard-content object) => content
Arguments:
object -- a gdk:clipboard object
content -- a gdk:content-provider instance
Details:
Accessor of the content slot of the gdk:clipboard class. The gdk:clipboard-content function returns the gdk:content-provider object currently set on clipboard. If the clipboard is empty or its contents are not owned by the current process, nil will be returned.
Notes:
The content property is not writeable. Use the gdk:clipboard-set-content function to set the content provider.
See also:
2023-7-30
Accessor gdk:clipboard-display (object)
Syntax:
(gdk:clipboard-display object) => display
Arguments:
object -- a gdk:clipboard object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:clipboard class. The gdk:clipboard-display function returns the display that the clipboard was created for.
See also:
2023-7-30
Accessor gdk:clipboard-formats (object)
Syntax:
(gdk:clipboard-formats object) => formats
Arguments:
object -- a gdk:clipboard object
formats -- a gdk:content-formats instance
Details:
Accessor of the formats slot of the gdk:clipboard class. The gdk:clipboard-formats function gets the formats that the clipboard can provide its current contents in.
See also:
2023-7-30
Accessor gdk:clipboard-local (object)
Syntax:
(gdk:clipboard-local object) => local
Arguments:
object -- a gdk:clipboard object
local -- a boolean whether the contents of the clipboard are owned by this process
Details:
Accessor of the local slot of the gdk:clipboard class. The gdk:clipboard-local function returns whether the clipboard is local. See also the gdk:clipboard-is-local function.
See also:
2023-7-30
Function gdk:clipboard-is-local (clipboard)
Arguments:
clipboard -- a gdk:clipboard object
Returns:
True if the clipboard is local.
Details:
Returns if the clipboard is local. A clipboard is considered local if it was last claimed by the running application. Note that the gdk:clipboard-content function may return nil even on a local clipboard. In this case the clipboard is empty.
See also:
2023-7-30
Function gdk:clipboard-store-async (clipboard priority cancellable func)
Arguments:
clipboard -- a gdk:clipboard object
priority -- an integer with the I/O priority of the request
cancellable -- an optional g:cancellable instance, nil to ignore
func -- a g:async-ready-callback callback function to call when the request is satisfied
Details:
Asynchronously instructs the clipboard to store its contents remotely to preserve them for later usage. If the clipboard is not local, this function does nothing but report success.

This function is called automatically when the gtk:application object exit, so you likely do not need to call it.
See also:
#2023-7-30
Function gdk:clipboard-store-finish (clipboard result)
Arguments:
clipboard -- a gdk:clipboard object
result -- a g:async-result instance
Returns:
True if storing was successful.
Details:
Finishes an asynchronous clipboard store started with the gdk:clipboard-store-async function.
See also:
#2024-11-21
Function gdk:clipboard-read-value-async (clipboard gtype priority cancellable func)
Arguments:
clipboard -- a gdk:clipboard object
gtype -- a g:type-t type ID to read
priority -- an integer with the I/O priority of the request
cancellable -- an optional g:cancellable instance, nil to ignore
func -- a g:async-ready-callback callback function to call when the request is satisfied
Details:
Asynchronously request the clipboard contents converted to the given gtype. When the operation is finished the func callback function will be called. You can then call the gdk:clipboard-read-value-finish function to get the resulting value.

For local clipboard contents that are available in the given gtype, the value will be copied directly. Otherwise, GDK will try to use the gdk:content-deserialize-async function to convert the clipboard's data.
See also:
#2023-7-30
Function gdk:clipboard-read-value-finish (clipboard result)
Arguments:
clipboard -- a gdk:clipboard object
result -- a g:async-result instance
Returns:
The g:value instance which holds the value of the content of clipboard.
Details:
Finishes an asynchronous clipboard read started with the gdk:clipboard-read-value-async function.
See also:
#2024-11-21
Function gdk:clipboard-read-texture-async (clipboard cancellable func)
Arguments:
clipboard -- a gdk:clipboard object
cancellable -- an optional g:cancellable instance, nil to ignore
func -- a g:async-ready-callback callback function to call when the request is satisfied
Details:
Asynchronously request the clipboard contents converted to a gdk:pixbuf object. When the operation is finished the func callback function will be called. You can then call the gdk:clipboard-read-texture-finish function to get the result.

This is a simple wrapper around the gdk:clipboard-read-value-async function. Use that function directly if you need more control over the operation.
See also:
#2023-7-30
Function gdk:clipboard-read-texture-finish (clipboard result)
Arguments:
clipboard -- a gdk:clipboard object
result -- a g:async-result instance
Returns:
The gdk:texture object which holds the value of the content of clipboard.
Details:
Finishes an asynchronous clipboard read started with the gdk:clipboard-read-texture-async function.
See also:
#2024-11-21
Function gdk:clipboard-read-text-async (clipboard cancellable func)
Arguments:
clipboard -- a gdk:clipboard object
cancellable -- an optional g:cancellable instance, nil to ignore
func -- a g:async-ready-callback callback function to call when the request is satisfied
Details:
Asynchronously request the clipboard contents converted to a string. When the operation is finished the func callback function will be called. You can then call the gdk:clipboard-read-text-finish function to get the result.

This is a simple wrapper around the gdk:clipboard-read-value-async function. Use that function directly if you need more control over the operation.
See also:
#2023-7-30
Function gdk:clipboard-read-text-finish (clipboard result)
Arguments:
clipboard -- a gdk:clipboard object
result -- a g:async-result instance
Returns:
The string which holds the value of the content of clipboard.
Details:
Finishes an asynchronous clipboard read started with the gdk:clipboard-read-text-async function.
See also:
#2024-11-21
Function gdk:clipboard-set-content (clipboard provider)
Arguments:
clipboard -- a gdk:clipboard object
content -- a new gdk:content-provider object or nil to clear the clipboard
Returns:
True if setting the clipboard succeeded.
Details:
Sets a new content provider on clipboard. The clipboard will claim the resources of the gdk:display object and advertise these new contents to other applications.

In the rare case of a failure, this function will return false. The clipboard will then continue reporting its old contents and ignore provider.

If the contents are read by either an external application or the read functions of the clipboard, clipboard will select the best format to transfer the contents and then request that format from provider.
See also:
2023-7-30
Function gdk:clipboard-set (clipboard gtype value)
Arguments:
clipboard -- a gdk:clipboard object
gtype -- a g:type-t type ID of value to set
value -- a Lisp value to be set
Details:
Sets the clipboard to contain the given value.
Notes:
This function intializes a g:value instance of the given gtype, stores value in the g:value instance and calls the gdk:clipboard-set-value function.
See also:
#2023-7-30
Function gdk:clipboard-set-value (clipboard gvalue)
Arguments:
clipoboard -- a gdk:clipboard object
gvalue -- a g:value instance
Details:
Sets the clipboard to contain the given gvalue.
Notes:
This function is called from the gdk:clipboard-set function to store the g:value instance into the clipboard.
See also:
#2023-7-30
Function gdk:clipboard-set-text (clipboard text)
Arguments:
clipboard -- a gdk:clipboard object
text -- a string with the text to put into the clipboard
Details:
Puts the given text into the clipboard.
See also:
#2023-7-30
Function gdk:clipboard-set-texture (clipboard texture)
Arguments:
clipboard -- a gdk:clipboard object
texture -- a gdk:texture object to put into the clipboard
Details:
Puts the given texture into the clipboard.
See also:
#2023-7-30

GdkDrag

GEnum gdk:drag-cancel-reason
Declaration:
    
(gobject:define-genum "GdkDragCancelReason" drag-cancel-reason
  (:export t
   :type-initializer "gdk_drag_cancel_reason_get_type")
  :no-target
  :user-cancelled
  :error)    
Values:
:no-target
There is no suitable drop target.
:user-cancelled
Drag cancelled by the user.
:error
Unspecified error.
Details:
Used in the gdk:drag object to the reason of a cancelled DND operation.
See also:
2024-5-2
GFlags gdk:drag-action
Declaration:
    
(gobject:define-gflags "GdkDragAction" drag-action
  (:export t
   :type-initializer "gdk_drag_action_get_type")
  (:none 0)
  (:copy #.(ash 1 0))
  (:move #.(ash 1 1))
  (:link #.(ash 1 2))
  (:ask #.(ash 1 3)))    
Values:
:copy
Copy the data.
:move
Move the data, that is, first copy it, then delete it from the source using the DELETE target of the X selection protocol.
:link
Add a link to the data. Note that this is only useful if source and destination agree on what it means, and is not supported on all platforms.
:ask
Ask the user what to do with the data.
Details:
Used in gdk:drop and gdk:drag objects to indicate the actions that the destination can and should do with the dropped data.
See also:
2024-7-12
Class gdk:drag
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
actions
The actions property of type gdk:drag-action (Read / Write)
The possible actions of the drag.
Default value: :none
content
The content property of type gdk:content-provider (Read / Write / Construct Only)
The content provider.
device
The device property of type gdk:device (Read / Write / Construct Only)
The device that is performing the drag.
display
The display property of type gdk:display (Read)
The display that the drag belongs to.
formats
The formats property of type gdk:content-formats (Read / Write / Construct Only)
The possible content formats that the drag can provide its data in.
selected-action
The selected-action property of type gdk:drag-action (Read / Write)
The currently selected action of the drag.
Default value: :none
surface
The surface property of type gdk:surface (Read / Write / Construct Only)
The surface where the drag originates.
Slot Access Functions:
Details:
The gdk:drag object represents the source of an ongoing DND operation. A gdk:drag object is created when a drag is started, and stays alive for duration of the DND operation. After a drag has been started with the gdk:drag-begin function, the caller gets informed about the status of the ongoing drag operation with signals on the gdk:drag object.

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the "Drag and Drop" section of the GTK documentation for more information.
Signal Details:
The "cancel" signal
lambda (drag reason)    :run-last      
drag
The gdk:drag object on which the signal is emitted.
reason
The gdk:drag-cancel-reason value with the reason the drag was cancelled.
The drag operation was cancelled.
The "dnd-finished" signal
lambda (drag)    :run-last      
drag
The gdk:drag object on which the signal is emitted.
The drag operation was finished, the destination finished reading all data. The drag object can now free all miscellaneous data.
The "drop-performed" signal
lambda (drag)    :run-last      
drag
The gdk:drag object on which the signal is emitted.
The drag operation was performed on an accepting client.
See also:
2024-5-2
Accessor gdk:drag-actions (object)
Syntax:
(gdk:drag-actions object) => actions
Arguments:
object -- a gdk:drag object
actions -- a gdk:drag-action value
Details:
Accessor of the actions slot of the gdk:drag class. The gdk:drag-actions function determines the possible actions proposed by the drag source.
See also:
#2024-5-2
Accessor gdk:drag-content (object)
Syntax:
(gdk:drag-content object) => content
Arguments:
object -- a gdk:drag object
content -- a gdk:content-provider object associated to object
Details:
Accessor of the content slot of the gdk:drag class. The gdk:drag-content function returns the content provider associated to the drag object.
See also:
#2024-5-2
Accessor gdk:drag-device (object)
Syntax:
(gdk:drag-device object) => device
Arguments:
object -- a gdk:drag object
device -- a gdk:device object associated to object
Details:
Accessor of the device slot of the gdk:drag class. The gdk:drag-device function returns the device associated to the drag object.
See also:
#2024-5-2
Accessor gdk:drag-display (object)
Syntax:
(gdk:drag-display object) => display
Arguments:
object -- a gdk:drag object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:drag class. The gdk:drag-display function returns the display that the drag object was created for.
See also:
#2024-5-2
Accessor gdk:drag-formats (object)
Syntax:
(gdk:drag-formats object) => formats
Arguments:
object -- a gdk:drag object
formats -- a gdk:content-formats object
Details:
Accessor of the formats slot of the gdk:drag class. The gdk:drag-formats function retrieves the formats supported by the drag object.
See also:
#2024-5-2
Accessor gdk:drag-selected-action (object)
Syntax:
(gdk:drag-selected-action object) => action
Arguments:
object -- a gdk:drag object
action -- a gdk:drag-action value
Details:
Accessor of the selected-action slot of the gdk:drag class. The gdk:drag-selected-action function determines the action chosen by the drag destination.
See also:
#2024-5-2
Accessor gdk:drag-surface (object)
Syntax:
(gdk:drag-surface object) => surface
Arguments:
object -- a gdk:drag object
surface -- a gdk:surface object where the drag originates
Details:
Accessor of the surface slot of the gdk:drag class. The gdk:drag-surface function returns the surface where the drag originates.
See also:
#2024-5-2
Function gdk:drag-drop-done (drag success)
Arguments:
drag -- a gdk:drag object
success -- a boolean whether the drag was ultimatively successful
Details:
Inform GDK if the drop ended successfully. Passing false for success may trigger a drag cancellation animation. This function is called by the drag source, and should be the last call before dropping the reference to the drag object.

The gdk:drag object will only take the first gdk:drag-drop-done function call as effective, if this function is called multiple times, all subsequent calls will be ignored.
See also:
#2024-1-7
Function gdk:drag-begin (surface device content actions dx dy)
Arguments:
surface -- a gdk:surface object for this drag object
device -- a gdk:device object that controls the drag object
content -- a gdk:content-provider object with the offered content
actions -- a gdk:drag-action value with the actions supported by this drag object
dx -- a double float with the x offset to the position of the device where the drag nominally started
dy -- a double float with the y offset to the position of the device where the drag nominally started
Returns:
The newly created gdk:drag object of nil on error.
Details:
Starts a drag and creates a new drag context for it. This function is called by the drag source. After this call, you probably want to set up the drag icon using the surface returned by the gdk:drag-drag-surface function.

This function returns a reference to the gdk:drag object, but GTK keeps its own reference as well, as long as the DND operation is going on.

Note: If actions include :move, you need to listen for the "dnd-finished" signal and delete the data at the source if the gdk:drag-selected-action function returns :move.
See also:
#2024-1-7
Function gdk:drag-drag-surface (drag)
Arguments:
drag -- a gdk:drag object
Returns:
The gdk:surface object or nil.
Details:
Returns the surface on which the drag icon should be rendered during the drag operation. Note that the surface may not be available until the drag operation has begun. GDK will move the surface in accordance with the ongoing drag operation. The surface is owned by drag and will be destroyed when the drag operation is over.
See also:
#2024-1-7
Function gdk:drag-set-hotspot (drag xhotspot yhotspot)
Arguments:
drag -- a gdk:drag object
xhotspot -- a double float with the x coordinate of the drag surface hotspot
yhotspot -- a double float with the y coordinate of the drag surface hotspot
Details:
Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface.
See also:
#2023-8-6
Function gdk:drag-action-is-unique (action)
Arguments:
action -- a gdk:drag-action value
Returns:
True if exactly one action was given.
Details:
Checks if action represents a single action or if it includes multiple flags that can be selected from. When action is :none, that is no action was given, true is returned.
See also:
#2024-7-12

GdkDrop

Class gdk:drop
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
actions
The actions property of type gdk:drag-action (Read / Write / Construct Only)
The possible actions for the drop.
Default value: '(:copy :move :link)
device
The device property of type gdk:device (Read / Write / Construct Only)
The device performing the drop.
display
The display property of type gdk:display (Read)
The display that the drop object belongs to.
drag
The drag property of type gdk:drag (Read / Write / Construct Only)
The drag object that initiated the drop.
formats
The formats property of type gdk:content-formats (Read / Write / Construct Only)
The possible formats that the drop object can provide its data in.
surface
The surface property of type gdk:surface (Read / Write / Construct Only)
The surface the drop happens on.
Details:
The gdk:drop object represents the target side of an ongoing DND operation. Possible drop sites get informed about the status of the ongoing drag operation with events of :enter, :leave, :motion and :start type. The gdk:drop object can be obtained from these gdk:events events using the gdk:dnd-event-drop function.

The actual data transfer is initiated from the target side via an async read, using one of the gdk:drop functions for this purpose: the gdk:drop-read-async or gdk:drop-read-value-async functions.

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the Drag and Drop section of the GTK documentation for more information.
See also:
#2023-8-7
Accessor gdk:drop-actions (object)
Syntax:
(gdk:drop-actions object) => actions
Arguments:
object -- a gdk:drop object
actions -- a gdk:drag-action value
Details:
Accessor of the actions slot of the gdk:drop class. The gdk:drop-actions function returns the possible actions for the drop object. If this value contains multiple actions, that is, the gdk:drag-action-is-unique function returns false for the result, the gdk:drop-finish function must choose the action to use when accepting the drop. This will only happen if you passed :ask as one of the possible actions in the gdk:drop-status function. The :ask value itself will not be included in the actions returned by this function.

This value may change over the lifetime of the drop object both as a response to source side actions as well as to calls to the gdk:drop-status function or the gdk:drop-finish function. The source side will not change this value anymore once a drop has started.
See also:
#2024-7-12
Accessor gdk:drop-device (object)
Syntax:
(gdk:drop-device object) => device
Arguments:
object -- a gdk:drop object
device -- a gdk:device object performing the drop
Details:
Accessor of the device slot of the gdk:drop class. The gdk:drop-device function returns the device performing the drop.
See also:
#2023-8-7
Accessor gdk:drop-drag (object)
Syntax:
(gdk:drop-drag object) => drag
Arguments:
object -- a gdk:drop object
drag -- a corresponding gdk:drag object
Details:
Accessor of the drag slot of the gdk:drop class. If this is an in-app drag-and-drop operation, returns the drag object that corresponds to this drop. If it is not, nil is returned.
See also:
#2023-8-7
Accessor gdk:drop-formats (object)
Syntax:
(gdk:drop-formats object) => formats
Arguments:
object -- a gdk:drop object
formats -- a gdk:content-formats instance
Details:
Accessor of the formats slot of the gdk:drop class. The gdk:drop-formats function returns the content formats that the drop offers the data to be read in.
See also:
#2023-8-7
Accessor gdk:drop-surface (object)
Syntax:
(gdk:drop-surface object) => surface
Arguments:
object -- a gdk:drop object
surface -- a gdk:surface object performing the drop
Details:
Accessor of the surface slot of the gdk:drop class. The gdk:drop-surface function returns the surface performing the drop.
See also:
#2023-8-7
Function gdk:drop-status (drop actions preferred)
Arguments:
drop -- a gdk:drop object
actions -- a gdk:drag-action value with the supported actions of the destination, or :none to indicate that a drop will not be accepted
preferred -- a gdk:drag-action value with the unique action that is a member of actions indicating the preferred action
Details:
Selects all actions that are potentially supported by the destination. When calling this function, do not restrict the passed in actions to the ones provided by the gdk:drop-actions function. Those actions may change in the future, even depending on the actions you provide here.

The preferred action is a hint to the drag'n'drop mechanism about which action to use when multiple actions are possible.

This function should be called by drag destinations in response to :enter or :motion events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again.
See also:
#2023-8-7
Function gdk:drop-finish (drop action)
Arguments:
drop -- a gdk:drop object
action -- a gdk:drag-action value with the action performed by the destination or :none if the drop failed
Details:
Ends the drag operation after a drop. The action must be a single action selected from the actions available via the gdk:drop-actions function.
See also:
#2023-8-7
Function gdk:drop-read-value-async (drop gtype priority cancellable func)
Arguments:
drop -- a gdk:drop object
gtype -- a g:type-t type ID to read
priority -- an integer with the I/O priority of the request
cancellable -- an optional g:cancellable object, nil to ignore
func -- a g:async-ready-callback callback function to call when the request is satisfied
Details:
Asynchronously request the drag operation's contents converted to the given gtype. When the operation is finished func will be called. You can then call the gdk:drop-read-value-finish function to get the resulting g:value value.

For local drag'n'drop operations that are available in the given gtype, the value will be copied directly. Otherwise, GDK will try to use the gdk:content-deserialize-async to convert the data.
See also:
#2023-8-7
Function gdk:drop-read-value-finish (drop result)
Arguments:
drop -- a gdk:drop object
result -- a g:async-result object
Returns:
The g:value value containing the result.
Details:
Finishes an async drop read started with the gdk:drop-read-value-async function.
See also:
#2024-11-21

GdkDragSurface

CStruct gdk:drag-surface-size
Details:
The gdk:drag-surface-size structure contains information that is useful to compute the size of a drag surface.

Since 4.12
See also:
#2023-11-4
Function gdk:drag-surface-size-set-size (size width height)
Arguments:
size -- a gdk:drag-surface-size instance
width -- an integer with the width
height -- an integer with the height
Details:
Sets the size the drag surface prefers to be resized to.

Since 4.12
See also:
#2023-11-4
Interface gdk:drag-surface
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:drag-surface interface is an interface for surfaces used during DND.
Signal Details:
The "compute-size" signal
lambda (surface size)    :run-last      
surface
The gdk:drag-surface object.
size
The gdk:drag-surface-size instance with the size of the drag surface.
Emitted when the size for the surface needs to be computed, when it is present. This signal will normally be emitted during the native surface layout cycle when the surface size needs to be recomputed. It is the responsibility of the drag surface user to handle this signal and compute the desired size of the surface, storing the computed size in the gdk:drag-surface-size instance that is passed to the signal handler, using the gdk:drag-surface-size-set-size function. Failing to set a size so will result in an arbitrary size being used as a result. Since 4.12
See also:
2024-11-7
Function gdk:drag-surface-present (surface width height)
Arguments:
surface -- a gdk:drag-surface object to show
width -- an integer with the unconstrained surface width to layout
height -- an integer with the unconstrained surface height to layout
Returns:
False if the drag surface failed to be presented, otherwise true.
Details:
Present the drag surface.
See also:
#2023-11-4

Application launching

GdkAppLaunchContext

Class gdk:app-launch-context
Superclasses:
gio:app-launch-context, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
display
The display property of type gdk:display (Read / Write / Construct Only)
The display that the launch context is for.
Slot Access Functions:
Details:
The gdk:app-launch-context object is an implementation of the g:app-launch-context object that handles launching an application in a graphical context. It provides startup notification and allows to launch applications on a specific screen or workspace.
Examples:
Launching an application.
(let* ((display (gdk:display-default))
       (context (gdk:display-app-launch-context display)))
  (unless (g:app-info-launch-default-for-uri "http://www.gtk.org" context)
    (warn "Launching failed")))    
See also:
2025-1-1
Accessor gdk:app-launch-context-display (object)
Syntax:
(gdk:app-launch-context-display object) => display
Arguments:
object -- a gdk:app-launch-context object
display -- a gdk:display object
Details:
Accessor of the display slot of the gdk:app-launch-context class. The gdk:app-launch-context-display function gets the display that the launch context is for.
See also:
2025-1-1
Function gdk:app-launch-context-set-desktop (context desktop)
Arguments:
context -- a gdk:app-launch-context object
desktop -- an integer with the number of a workspace, or -1
Details:
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. When the workspace is not specified or the desktop argument is set to -1, it is up to the window manager to pick one, typically it will be the current workspace.
See also:
2025-1-1
Function gdk:app-launch-context-set-timestamp (context timestamp)
Arguments:
context -- a gdk:app-launch-context object
timestamp -- an unsigned integer with a timestamp
Details:
Sets the timestamp of context. The timestamp should ideally be taken from the event that triggered the launch. Window managers can use this information to avoid moving the focus to the newly launched application when the user is busy typing in another window. This is also known as 'focus stealing prevention'.
See also:
2025-1-1
Function gdk:app-launch-context-set-icon (context icon)
Arguments:
context -- a gdk:app-launch-context object
icon -- a g:icon object, or nil
Details:
Sets the icon for applications that are launched with this context. Window Managers can use this information when displaying startup notification. See also the gdk:app-launch-context-set-icon-name function.
See also:
2025-1-1
Function gdk:app-launch-context-set-icon-name (context name)
Arguments:
context -- a gdk:app-launch-context object
name -- a string with an icon name, or nil
Details:
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 the gdk:app-launch-context-set-icon function. If both an icon and an icon name are set, the icon name takes priority. If neither an icon or an icon name is set, the icon is taken from either the file that is passed to launched application or from the g:app-info object for the launched application itself.
See also:
2025-1-1

GDK Miscellaneous

Events

Constant gdk:+current-time+
Initial Value:
0
Details:
Represents the current time, and can be used anywhere a time is expected.
2024-7-26
Constant gdk:+event-propagate+
Initial Value:
false
Details:
Use this value as the return value for continuing the propagation of an event handler.
See also:
2024-4-1
Constant gdk:+event-stop+
Initial Value:
true
Details:
Use this value as the return value for stopping the propagation of an event handler.
Examples:
This event handler for the "close-request" signal of a window stops the propagation of the event and the window is not closed.
(g:signal-connect window "close-request"
                  (lambda (widget event)
                    (declare (ignore widget event))
                    gdk:+event-stop+))    
See also:
2024-4-1
Constant gdk:+button-primary+
Initial Value:
1
Details:
The primary button. This is typically the left mouse button, or the right button in a left-handed setup.
See also:
2025-2-11
Constant gdk:+button-middle+
Initial Value:
2
Details:
The middle button.
See also:
2025-2-11
Constant gdk:+button-secondary+
Initial Value:
3
Details:
The secondary button. This is typically the right mouse button, or the left button in a left-handed setup.
See also:
2025-2-11
GEnum gdk:event-type
Declaration:
(gobject:define-genum "GdkEventType" event-type
  (:export t
   :type-initializer "gdk_event_type_get_type")
  (:nothing -1)
  :delete
  :motion-notify
  :button-press
  :button-release
  :key-press
  :key-release
  :enter-notify
  :leave-notify
  :focus-change
  :proximity-in
  :proximity-out
  :drag-enter
  :drag-leave
  :drag-motion
  :drop-start
  :scroll
  :grab-broken
  :touch-begin
  :touch-update
  :touch-end
  :touch-cancel
  :touchpad-swipe
  :touchpad-pinch
  :pad-button-press
  :pad-button-release
  :pad-ring
  :pad-strip
  :pad-group-mode
  :touchpad-hold
  :event-last)  
Values:
:nothing
The special code to indicate a null event.
:delete
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.
:motion-notify
The pointer, usually a mouse, has moved.
:button-press
The mouse button has been pressed.
:button-release
The mouse button has been released.
:key-press
The key has been pressed.
:key-release
The key has been released.
:enter-notifiy
The pointer has entered the window.
:leave-notify
The pointer has left the window.
:focus-change
The keyboard focus has entered or left the window.
:proximity-in
The input device has moved into contact with a sensing surface, for example, a touchscreen or graphics tablet.
:proximity-out
The input device has moved out of contact with a sensing surface.
:drag-enter
The mouse has entered the window while a drag is in progress.
:drag-leave
The mouse has left the window while a drag is in progress.
:drag-motion
The mouse has moved in the window while a drag is in progress.
:drop-start
The drop operation onto the window has started.
:scroll
The scroll wheel was turned.
:grab-broken
The pointer or keyboard grab was broken.
:touch-begin
The new touch event sequence has just started.
:touch-update
The touch event sequence has been updated.
:touch-end
The touch event sequence has finished.
:touch-cancel
The touch event sequence has been canceled.
:touchpad-swipe
The touchpad swipe gesture event, the current state is determined by its phase field.
:touchpad-pinch
The touchpad pinch gesture event, the current state is determined by its phase field.
:pad-button-press
The tablet pad button press event.
:pad-button-release
The tablet pad button release event.
:pad-ring
The tablet pad axis event from a "ring".
:pad-strip
The tablet pad axis event from a "strip".
:pad-group-mode
The tablet pad group mode change.
:touchpad-hold
The touchpad hold gesture event, the current state is determined by its phase field. Since 4.6
:event-last
Marks the end of the gdk:event-type enumeration.
Details:
Specifies the type of a gdk:event instance.
See also:
2024-7-12
GEnum gdk:key-match
Declaration:
(gobject:define-genum "GdkKeyMatch" key-match
  (:export t
   :type-initializer "gdk_key_match_get_type")
  (:none 0)
  (:partial 1)
  (:exact 2))  
Values:
:none
The key event does not match.
:partial
The key event matches if keyboard state (specifically, the currently active group) is ignored.
:exact
The key event matches.
Details:
Describes how well an event matches a given keyval and modifiers. The gdk:key-match values are returned by the gdk:key-event-matches function.
See also:
2024-5-26
GEnum gdk:touchpad-gesture-phase
Declaration:
(gobject:define-genum "GdkTouchpadGesturePhase" touchpad-gesture-phase
  (:export t
   :type-initializer "gdk_touchpad_gesture_phase_get_type")
  (:begin 0)
  (:update 1)
  (:end 2)
  (:cancel 3))  
Values:
:begin
The gesture has begun.
:update
The gesture has been updated.
:end
The gesture was finished, changes should be permanently applied.
:cancel
The gesture was cancelled, all changes should be undone.
Details:
The gdk:touchpad-gesture-phase enumeration specifies the current state of a touchpad gesture. All gestures are guaranteed to begin with an event with :begin phase, followed by 0 or several events with :update phase.

A finished gesture may have 2 possible outcomes, an event with :end phase will be emitted when the gesture is considered successful, this should be used as the hint to perform any permanent changes.

Cancelled gestures may be so for a variety of reasons, due to hardware or the compositor, or due to the gesture recognition layers hinting the gesture did not finish resolutely, for example, a 3rd finger being added during a pinch gesture. In these cases, the last event will report the :cancel phase, this should be used as a hint to undo any visible/permanent changes that were done throughout the progress of the gesture.
See also:
2024-7-12
GEnum gdk:scroll-direction
Declaration:
(gobject:define-genum "GdkScrollDirection" scroll-direction
  (:export t
   :type-initializer "gdk_scroll_direction_get_type")
  (:up 0)
  (:down 1)
  (:left 2)
  (:right 3)
  (:smooth 4))  
Values:
:up
The window is scrolled up.
:down
The window is scrolled down.
:left
The window is scrolled to the left.
:right
The window is scrolled to the right.
:smooth
The scrolling is determined by the delta values in the gdk:scroll-event event. See the gdk:scroll-event-deltas function.
Details:
Specifies the direction for a gdk:scroll-event event.
See also:
2024-5-26
GEnum gdk:crossing-mode
Declaration:
(gobject:define-genum "GdkCrosssingMode" crossing-mode
  (:export t
   :type-initializer "gdk_crossing_mode_get_type")
  :normal
  :grab
  :ungrab
  :gtk-grab
  :gtk-ungrab
  :state-changed
  :touch-begin
  :touch-end
  :device-switch)  
Values:
:normal
Crossing because of pointer motion.
:grab
Crossing because a grab is activated.
:ungrab
Crossing because a grab is deactivated.
:gtk-grab
Crossing because a GTK grab is activated.
:gtk-ungrab
Crossing because a GTK grab is deactivated.
:state-changed
Crossing because a GTK widget changed state, for example, sensitivity.
:touch-begin
Crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the window.
:touch-end
Crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the window.
:device-switch
Crossing because of a device switch, that is, a mouse taking control of the pointer after a touch device, this event is synthetic as the pointer did not leave the window.
Details:
Specifies the crossing mode for enter and leave events.
See also:
2024-5-26
GEnum gdk:scroll-unit
Declaration:
(gobject:define-genum "GdkScrollUnit" scroll-unit
  (:export t
   :type-initializer "gdk_scroll_unit_get_type")
  :wheel
  :surface)  
Values:
:wheel
The delta is in number of wheel clicks.
:surface
The delta is in surface pixels to scroll directly on screen.
Details:
Specifies the unit of scroll deltas. When you get the :wheel value, a delta of 1.0 means 1 wheel detent click in the south direction, 2.0 means 2 wheel detent clicks in the south direction. This is the same logic for negative values but in the north direction.

If you get the :surface value, are managing a scrollable view and get a value of 123, you have to scroll 123 surface logical pixels right if it is delta_x or down if it is delta_y. This is the same logic for negative values but you have to scroll left instead of right if it is delta_x and up instead of down if it is delta_y.

1 surface logical pixel is equal to 1 real screen pixel multiplied by the final scale factor of your graphical interface, the product of the desktop scale factor and eventually a custom scale factor in your application.

Since 4.8
See also:
2024-5-26
GEnum gdk:notify-type
Declaration:
(gobject:define-genum notify-type
  (:export t
   :type-initializer "gdk_notify_type_get_type")
  (:ancestor 0)
  :virtual
  :inferior
  :nonlinear
  :nonlinear-virtual
  :unknown)  
Values:
:ancestor
The window is entered from an ancestor or left towards an ancestor.
:virtual
The pointer moves between an ancestor and an inferior of the window.
:inferior
The window is entered from an inferior or left towards an inferior.
:nonlinear
The window is entered from or left towards a window which is neither an ancestor nor an inferior.
:nonlinear-virtual
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.
:unknown
An unknown type of enter/leave event occurred.
Details:
Specifies the kind of crossing for enter and leave events. See the X11 protocol specification of LeaveNotify for full details of crossing event generation.
See also:
2024-5-26
GBoxed gdk:event-sequence
Details:
The gdk:event-sequence structure is an opaque type representing a sequence of related touch events. See the gdk:event-event-sequence function.
See also:
2023-12-17
GdkEvent gdk:event
Superclasses:
common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The base type of an event. In GTK applications the events are handled automatically by toplevel widgets and passed on to the event controllers of appropriate widgets, so these functions are rarely needed.
#2023-7-25
GdkEvent gdk:button-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a button on a pointer device.
See also:
#2023-7-25
GdkEvent gdk:scroll-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a scrolling motion.
See also:
#2023-7-25
GdkEvent gdk:motion-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a pointer or touch device motion.
See also:
#2023-7-25
GdkEvent gdk:key-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a key-based device.
See also:
#2023-7-25
GdkEvent gdk:focus-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a focus change.
See also:
#2023-7-25
GdkEvent gdk:crossing-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event caused by a pointing device moving between surfaces.
See also:
#2023-7-25
GdkEvent gdk:grab-broken-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a broken windowing system grab.
See also:
#2023-7-25
GdkEvent gdk:delete-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to closing a toplevel surface.
See also:
#2023-7-25
GdkEvent gdk:dnd-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to drag and drop operations.
See also:
#2023-7-25
GdkEvent gdk:touch-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a touch-based device.
See also:
#2023-7-25
GdkEvent gdk:touchpad-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a touchpad device.
See also:
#2023-7-25
GdkEvent gdk:pad-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to a pad-based device.
See also:
#2023-7-25
GdkEvent gdk:proximity-event
Superclasses:
gdk:event, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An event related to the proximity of a tool to a device.
See also:
#2023-7-25
Function gdk:event-event-type (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:event-type value.
Details:
Retrieves the type of the event.
See also:
#2023-7-25
Function gdk:event-surface (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:surface object.
Details:
Extracts the surface associated with an event.
See also:
#2023-7-25
Function gdk:event-device (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:device object.
Details:
Returns the device of an event.
See also:
#2023-7-25
Function gdk:event-device-tool (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:device-tool object, or nil.
Details:
If the event was generated by a device that supports different tools, for example a tablet, this function will return a gdk:device-tool object representing the tool that caused the event. Otherwise, nil will be returned.
Notes:
The gdk:device-tool objects will be constant during the application lifetime, if settings must be stored persistently across runs, see the gdk:device-tool-serial function.
See also:
#2024-7-12
Function gdk:event-time (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the time stamp field from event.
Details:
Returns the time stamp from event, if there is one, otherwise returns gdk:+current-time+.
See also:
#2023-7-25
Function gdk:event-display (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:display object.
Details:
Retrieves the display associated to the event.
See also:
#2023-7-25
Function gdk:event-seat (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:seat object.
Details:
Returns the seat that originated the event.
See also:
#2023-7-25
Function gdk:event-event-sequence (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:event-sequence instance that the event belongs to.
Details:
If the event is a touch event, returns the gdk:event-sequence instance to which the event belongs. Otherwise, return nil.
See also:
#2023-7-25
Function gdk:event-modifier-state (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:modifier-type value with the modifier state of event.
Details:
Returns the modifier state field of an event.
See also:
#2023-7-25
Function gdk:event-position (event)
Arguments:
event -- a gdk:event instance
Returns:
x - a double float with the event surface x coordinate
y - a double float with the event surface y coordinate
Details:
Extract the event surface relative x/y coordinates from an event.
See also:
#2023-7-25
Function gdk:event-axes (event)
Arguments:
event -- a gdk:event instance
Returns:
The list of double float with the values for all axes.
Details:
Extracts all axis values from an event.
See also:
#2023-7-25
Function gdk:event-axis (event axis-use)
Arguments:
event -- a gdk:event instance
axis-use -- a gdk:axis-use value with the axis use to look for
Returns:
The double float with the axis value.
Details:
Extract the axis value for a particular axis use from an event instance.
See also:
#2023-7-25
Function gdk:event-pointer-emulated (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the event is emulated.
Details:
Returns whether this event is an emulated pointer event, typically from a touch event, as opposed to a real one.
See also:
#2023-7-25
Function gdk:event-triggers-context-menu (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the event should trigger a context menu.
Details:
This function returns whether an event should trigger a context menu, according to platform conventions. The right mouse button always triggers context menus.
See also:
#2023-7-25
Function gdk:button-event-button (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the button of event.
Details:
Extract the button number from a button event.
See also:
#2023-7-25
Function gdk:scroll-event-direction (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:scroll-direction value with the direction of event.
Details:
Extracts the direction of a scroll event.
See also:
#2023-7-25
Function gdk:scroll-event-deltas (event)
Arguments:
event -- a gdk:event instance
Returns:
xdelta - a double float with the x scroll delta
ydelta - a double float with the y scroll delta
Details:
Extracts the scroll deltas of a scroll event. The deltas will be zero unless the scroll direction is the :smooth value of the gdk:scroll-direction enumeration.
See also:
#2023-7-25
Function gdk:scroll-event-is-stop (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the event is a scroll stop event.
Details:
Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, for example, by lifting a finger. This stop scroll event is the signal that a widget may trigger kinetic scrolling based on the current velocity.

Stop scroll events always have a delta of 0/0.
See also:
#2024-7-12
Function gdk:scroll-event-unit (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:scroll-unit value.
Details:
Extracts the scroll delta unit of a scroll event. The unit will always be :wheel if the scroll direction is not :smooth.

Since 4.8
See also:
#2024-11-10
Function gdk:key-event-keyval (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the keyval of event.
Details:
Extracts the keyval from a key event.
See also:
#2023-7-25
Function gdk:key-event-keycode (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the keycode of event.
Details:
Extracts the keycode from a key event.
See also:
#2023-7-25
Function gdk:key-event-consumed-modifiers (event)
Arguments:
event -- a gdk:event instance
Returns:
Details:
Extracts the consumed modifiers from a key event.
See also:
#2023-7-25
Function gdk:key-event-layout (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the layout of event.
Details:
Extracts the layout from a key event.
See also:
#2023-7-25
Function gdk:key-event-level (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the shift level of event.
Details:
Extracts the shift level from a key event.
See also:
#2023-7-25
Function gdk:key-event-is-modifier (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the event is for a modifier key.
Details:
Extracts whether the key event is for a modifier key.
See also:
#2023-7-25
Function gdk:key-event-matches (event keyval modifiers)
Arguments:
event -- a gdk:event instance
keyval -- an unsigned integer with the keyval to match
modifiers -- a gdk:modifier-type value to match
Returns:
The gdk:key-match value describing whether event matches.
Details:
Matches a key event against a keyboard shortcut that is specified as a keyval and modifiers. Partial matches are possible where the combination matches if the currently active group is ignored.

Note that we ignore the Caps Lock key for matching.
See also:
#2023-7-23
Function gdk:key-event-match (event)
Arguments:
event -- a gdk:event instance
Returns:
keyval - an unsigned integer with the keyval
modifiers - a gdk:modifier-type value
Details:
Gets a keyval and modifier combination that will cause the gdk:key-event-matches function to successfully match the given event.
See also:
#2023-7-25
Function gdk:focus-event-in (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the focus is entering.
Details:
Extracts whether this event is about focus entering or leaving the surface.
See also:
#2023-7-25
Function gdk:touch-event-emulating-pointer (event)
Arguments:
event -- a gdk:event instance
Returns:
True if event is emulating.
Details:
Extracts whether a touch event is emulating a pointer event.
See also:
#2023-7-25
Function gdk:crossing-event-mode (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:crossing-mode value with the mode of event.
Details:
Extracts the crossing mode from a crossing event.
See also:
#2023-7-25
Function gdk:crossing-event-detail (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:notify-type value with the detail of event.
Details:
Extracts the notify detail from a crossing event.
See also:
#2023-7-25
Function gdk:crossing-event-focus (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the surface is the focus surface.
Details:
Checks if the event surface is the focus surface.
See also:
#2023-7-25
Function gdk:grab-broken-event-grab-surface (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:surface object with the grab surface of event.
Details:
Extracts the grab surface from a grab broken event.
See also:
#2023-7-25
Function gdk:grab-broken-event-implicit (event)
Arguments:
event -- a gdk:event instance
Returns:
True if the an implicit grab was broken.
Details:
Checks whether the grab broken event is for an implicit grab.
See also:
#2023-7-25
Function gdk:dnd-event-drop (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:drop object.
Details:
Gets the gdk:drop object from a DND event.
See also:
#2023-7-25
Function gdk:touchpad-event-gesture-phase (event)
Arguments:
event -- a gdk:event instance
Returns:
The gdk:touchpad-gesture-phase value with the gesture phase of event.
Details:
Extracts the touchpad gesture phase from a touchpad event.
See also:
#2023-7-25
Function gdk:touchpad-event-n-fingers (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the number of fingers for event.
Details:
Extracts the number of fingers from a touchpad event.
See also:
#2023-7-25
Function gdk:touchpad-event-deltas (event)
Arguments:
event -- a gdk:event instance
Returns:
dx - a double float for dx
dy - a double float for dy
Details:
Extracts delta information from a touchpad event.
See also:
#2023-7-25
Function gdk:touchpad-event-pinch-angle-delta (event)
Arguments:
event -- a gdk:event instance
Returns:
The double float with the angle delta of event.
Details:
Extracts the angle delta from a touchpad pinch event.
See also:
#2023-7-25
Function gdk:touchpad-event-pinch-scale (event)
Arguments:
event -- a gdk:event instance
Returns:
The double float with the scale of event.
Details:
Extracts the scale from a touchpad pinch event.
See also:
#2023-7-25
Function gdk:pad-event-axis-value (event)
Arguments:
event -- a gdk:event instance
Returns:
index - an unsigned integer with the axis index
value - a double float with the axis value
Details:
Extracts the information from a pad strip or ring event.
See also:
#2023-5-25
Function gdk:pad-event-button (event)
Arguments:
event -- a gdk:event instance
Returns:
The unsigned integer with the button of event.
Details:
Extracts information about the pressed button from a pad event.
See also:
#2023-7-25
Function gdk:pad-event-group-mode (event)
Arguments:
event -- a gdk:event instance
Returns:
group - an unsigned integer with the group
mode - an unsigned integer wiht the mode
Details:
Extracts group and mode information from a pad event.
See also:
#2023-7-25
Function gdk:events-angle (event1 event2)
Arguments:
event1 -- a gdk:event instance
event2 -- a gdk:event instance
Returns:
The double float with the relative angle between both events.
Details:
If both events contain X/Y information, this function will return the relative angle from event1 to event2. The rotation direction for positive angles is from the positive X axis towards the positive Y axis.
See also:
#2023-5-25
Function gdk:events-center (event1 event2)
Arguments:
event1 -- a gdk:event instance
event2 -- a gdk:event instance
Returns:
x - a double float with the x coordinate of the center
y - a double float with the y coordinate of the center
Details:
If both events contain X/Y information, the center of both coordinates will be returned in x and y.
See also:
#2023-5-25
Function gdk:events-distance (event1 event2)
Arguments:
event1 -- a gdk:event instance
event2 -- a gdk:event instance
Returns:
The double float with the distance.
Details:
If both events have X/Y information, the distance between both coordinates, as in a straight line going from event1 to event2, will be returned.
See also:
#2023-5-25

Cursors

Class gdk:cursor
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
fallback
The fallback property of type gdk:cursor (Read / Write / Construct only)
Cursor image to fall back to if the cursor cannot be displayed.
hotspot-x
The hotspot-x property of type :int (Read / Write / Construct only)
Horizontal offset of the cursor hotspot.
Allowed values: >= 0
Default value: 0
hotspot-y
The hotspot-y property of type :int (Read / Write / Construct only)
Vertical offset of the cursor hotspot.
Allowed values: >= 0
Default value: 0
name
The name property of type :string (Read / Write / Construct only)
The name of the cursor.
Default value: nil
texture
The texture property of type gdk:texture (Read / Write / Construct only)
The texture displayed by this cursor.
Returned by:
Slot Access Functions:
Details:
The gdk:cursor object represents a cursor. Cursors are immutable objects, so once you created them, there is no way to modify them later. Create a new cursor when you want to change something about it.

Cursors by themselves are not very interesting, they must be bound to a window for users to see them. This is done with the gdk:surface-cursor or the gdk:surface-device-cursor functions. Applications will typically use higher-level GTK functions such as the gtk:widget-cursor function instead.

Cursors are not bound to a given gdk:display object, so they can be shared. However, the appearance of cursors may vary when used on different platforms.

There are multiple ways to create cursors. The platform's own cursors can be created with the gdk:cursor-new-from-name function. That function lists the commonly available names that are shared with the CSS specification. Other names may be available, depending on the platform in use. On some platforms, what images are used for named cursors may be influenced by the cursor theme.

Another option to create a cursor is to use the gdk:cursor-new-from-texture function and provide an image to use for the cursor.

To ease work with unsupported cursors, a fallback cursor can be provided. If a gdk:surface object cannot use a cursor because of the reasons mentioned above, it will try the fallback cursor. Fallback cursors can themselves have fallback cursors again, so it is possible to provide a chain of progressively easier to support cursors. If none of the provided cursors can be supported, the default cursor will be the ultimate fallback.
2024-6-30
Accessor gdk:cursor-fallback (object)
Syntax:
(gdk:cursor-fallback object) => fallback
Arguments:
object -- a gdk:cursor object
fallback -- a gdk:cursor object with the fallback of the cursor or nil to use the default cursor as fallback
Details:
Accessor of the fallback slot of the gdk:cursor class. The gdk:cursor-fallback function returns the fallback for cursor. The fallback will be used if the cursor is not available on a given gdk:display object.

For named cursors, this can happen when using nonstandard names or when using an incomplete cursor theme. For textured cursors, this can happen when the texture is too large or when the gdk:display object it is used on does not support textured cursors.
See also:
2024-6-30
Accessor gdk:cursor-hotspot-x (object)
Syntax:
(gdk:cursor-hotspot-x object) => hotspot
Arguments:
object -- a gdk:cursor object
hotspot -- an integer with the horizontal offset of the hotspot or 0 for named cursors
Details:
Accessor of the hotspot-x slot of the gdk:cursor class. The gdk:cursor-hotspot-x function returns the horizontal offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor.

Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with the gdk:cursor-new-from-texture function.
See also:
2024-6-30
Accessor gdk:cursor-hotspot-y (object)
Syntax:
(gdk:cursor-hotspot-y object) => hotspot
Arguments:
object -- a gdk:cursor object
hotspot -- an integer with the vertical offset of the hotspot or 0 for named cursors
Details:
Accessor of the hotspot-y slot of the gdk:cursor class. The gdk:cursor-hotspot-y function returns the vertical offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor.

Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with the gdk:cursor-new-from-texture function.
See also:
2024-6-30
Accessor gdk:cursor-name (object)
Syntax:
(gdk:cursor-name object) => name
Arguments:
object -- a gdk:cursor object
name -- a string with the name of the cursor or nil if it is not a named cursor
Details:
Accessor of the name slot of the gdk:cursor class. The gdk:cursor-name function returns the name of the cursor. If the cursor is not a named cursor, nil will be returned.
See also:
2024-6-30
Accessor gdk:cursor-texture (object)
Syntax:
(gdk:cursor-texture object) => texture
Arguments:
object -- a gdk:cursor object
texture -- a gdk:texture object with the texture for cursor or nil if it is a named cursor
Details:
Accessor of the texture slot of the gdk:cursor class. The gdk:cursor-texture function returns the texture for the cursor. If the cursor is a named cursor, nil will be returned.
See also:
2024-6-30
Function gdk:cursor-new-from-texture (texture xhotspot yhotspot &optional fallback)
Arguments:
texture -- a gdk:texture object with the texture providing the pixel data
xhotspot -- an integer with the horizontal offset of the hotspot of the cursor
yhotspot -- an integer with the vertical offset of the hotspot of the cursor
fallback -- an optional gdk:cursor object to fall back to when this one cannot be supported, the default is nil
Returns:
The new gdk:cursor object.
Details:
Creates a new cursor from a gdk:texture object.
See also:
2024-6-30
Function gdk:cursor-new-from-name (name &optional fallback)
Arguments:
name -- a string with the name of the cursor
fallback -- an optional gdk:cursor object to fall back to when this one cannot be supported, the default is nil
Returns:
The new gdk:cursor object, or nil if there is no cursor with the given name.
Details:
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"
"help"
"pointer"
"context-menu"
"progress"
"wait"
"cell"
"crosshair"
"text"
"vertical-text"
"alias"
"copy"
"no-drop"
"move"
"not-allowed"
"grab"
"grabbing"
"all-scroll"
"col-resize"
"row-resize"
"n-resize"
"e-resize"
"s-resize"
"w-resize"
"ne-resize"
"nw-resize"
"sw-resize"
"se-resize"
"ew-resize"
"ns-resize"
"nesw-resize"
"nwse-resize"
"zoom-in"
"zoom-out"
Examples:
(gdk:cursor-new-from-name "wait")
=> #<GDK:CURSOR {1013383A73}>    
See also:
2024-6-30

GdkFrameTimings

GBoxed gdk:frame-timings
Declaration:
(glib:define-gboxed-opaque frame-timings "GdkFrameTimings"
  :export t
  :type-initializer "gdk_frame_timings_get_type"
  :alloc (error "GdkFrameTimings cannot be created from the Lisp side."))  
Details:
The gdk:frame-timings structure holds timing information for a single frame of the application’s displays. To retrieve a gdk:frame-timings instance, use the gdk:frame-clock-timings or gdk:frame-clock-current-timings functions. The information in the gdk:frame-timings instance is useful for precise synchronization of video with the event or audio streams, and for measuring quality metrics for the display of the application, such as latency and jitter.
See also:
2025-3-1
Function gdk:frame-timings-frame-counter (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
The integer with the frame counter value for this frame.
Details:
Gets the frame counter value of the frame clock when this frame was drawn.
See also:
#2025-3-1
Function gdk:frame-timings-complete (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
True if all information that will be available for the frame has been filled in.
Details:
The timing information in a gdk:frame-timings instance 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 gdk:frame-timings instances can return 0 to indicate an unavailable value for two reasons: either because the information is not yet available, or because it is not available at all. Once the gdk:frame-timings-complete function returns true for a frame, you can be certain that no further values will become available and be stored in the gdk:frame-timings instance.
See also:
#2025-3-1
Function gdk:frame-timings-frame-time (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
The integer with the frame time for the frame.
Details:
Returns the frame time for the frame. This is the time value that is typically used to time animations for the frame. See the gdk:frame-clock-frame-time function.
See also:
#2025-3-1
Function gdk:frame-timings-presentation-time (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
The integer with the time the frame was displayed to the user, or 0 if no presentation time is available. See the gdk:frame-timings-complete function.
Details:
Returns the presentation time. This is the time at which the frame became visible to the user.
See also:
#2025-3-1
Function gdk:frame-timings-refresh-interval (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
The integer with the refresh interval of the display, in microseconds, or 0 if the refresh interval is not available. See the gdk:frame-timings-complete function.
Details:
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".
See also:
#2025-3-1
Function gdk:frame-timings-predicted-presentation-time (timings)
Arguments:
timings -- a gdk:frame-timings instance
Returns:
The integer with the predicted time at which the frame will be presented, or 0 if no predicted presentation time is available.
Details:
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 the gdk:frame-timings-presentation-time function, which is only available after the frame has been presented. In general, if you are simply animating, you should use the gdk:frame-clock-frame-time function 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.
See also:
#2025-3-1

GdkFrameClock

GFlags gdk:frame-clock-phase
Declaration:
(gobject:define-gflags "GdkFrameClockPhase" frame-clock-phase
  (:export t
   :type-initializer "gdk_frame_clock_phase_get_type")
  (:none 0)
  (:flush-events #.(ash 1 0))
  (:before-paint #.(ash 1 1))
  (:update #.(ash 1 2))
  (:layout #.(ash 1 3))
  (:paint #.(ash 1 4))
  (:resmue-events #.(ash 1 5))
  (:after-paint #.(ash 1 6)))  
Values:
:none
No phase.
:flush-events
Corresponds to "flush-events" signals. Should not be handled by applications.
:before-paint
Corresponds to "before-paint" signals. Should not be handled by applications.
:update
Corresponds to the "update" signal.
:layout
Corresponds to the "layout" signal. Should not be handled by applications.
:paint
Corresponds to the "paint" signal.
:resume-events
Corresponds to the "resume-events" signal. Should not be handled by applications.
:after-paint
Corresponds to the "after-paint" signal. Should not be handled by applications.
Details:
The gdk:frame-clock-phase enumeration is used to represent the different paint clock phases that can be requested. The elements of the enumeration correspond to the signals of the gdk:frame-clock object.
See also:
2025-3-1
Class gdk:frame-clock
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk:frame-clock object tells the application when to update and repaint a surface. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames). The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates.

The gdk:frame-clock object 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 the gdk:frame-clock-request-phase function. 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 gdk:frame-clock class for documentation of the phases. The :update value of the gdk:frame-clock-phase enumeration and the "update" signal are most interesting for application writers, and are used to update the animations, using the frame time given by the gdk:frame-clock-frame-time function.

The frame time is reported in microseconds and generally in the same timescale as the system 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 the gdk:frame-clock-frame-time function 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 the gdk:frame-clock-frame-time function and the value inside the "update" signal of the clock, they will stay exactly synchronized.
Signal Details:
The "after-paint" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The signal ends processing of the frame. Applications should generally not handle this signal.
The "before-paint" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The signal begins processing of the frame. Applications should generally not handle this signal.
The "flush-events" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The signal is used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal.
The "layout" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The 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.
The "paint" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The 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 emits GdkSurface::render signals, which are turned into GTK GtkWidget::snapshot signals.
The "resume-events" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The 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.
The "update" signal
lambda (clock)    :run-last      
clock
The gdk:frame-clock object emitting the signal.
The signal is emitted as the first step of toolkit and application processing of the frame. Animations should be updated using the gdk:frame-clock-frame-time function. Applications can connect directly to this signal, or use the gtk:widget-add-tick-callback function as a more convenient interface.
See also:
2025-3-1
Function gdk:frame-clock-frame-time (clock)
Arguments:
clock -- a gdk:frame-clock object
Returns:
The integer with a timestamp in microseconds.
Details:
Gets the time that should currently be used for animations. Inside the processing of a frame, it is the time used to compute the animation position of everything in a frame. Outside of a frame, it is the time of the conceptual "previous frame", which may be either the actual previous frame time, or if that is too old, an updated time.
See also:
2025-3-1
Function gdk:frame-clock-request-phase (clock phase)
Arguments:
clock -- a gdk:frame-clock object
phase -- a gdk:frame-clock-phase value for the phase that is requested
Details:
Asks the frame clock to run a particular phase. The signal corresponding to the requested phase will be emitted the next time the frame clock processes. Multiple calls to the gdk:frame-clock-request-phase function will be combined together and only one frame processed. If you are displaying animated content and want to continually request the :update phase for a period of time, you should use the gdk:frame-clock-begin-updating function instead, since this allows GTK to adjust system parameters to get maximally smooth animations.
See also:
#2025-3-1
Function gdk:frame-clock-begin-updating (clock)
Arguments:
clock -- a gdk:frame-clock object
Details:
Starts updates for an animation. Until a matching call to the gdk:frame-clock-end-updating function is made, the frame clock will continually request a new frame with the :update phase. This function may be called multiple times and frames will be requested until the gdk:frame-clock-end-updating function is called the same number of times.
See also:
#2025-3-1
Function gdk:frame-clock-end-updating (clock)
Arguments:
clock -- a gdk:frame-clock object
Details:
Stops updates for an animation. See the documentation for the gdk:frame-clock-begin-updating function.
See also:
#2025-3-1
Function gdk:frame-clock-frame-counter (clock)
Arguments:
clock -- a gdk:frame-clock object
Returns:
Inside frame processing, the unsigned integer of the frame counter for the current frame. Outside of frame processing, the frame counter for the last frame.
Details:
A frame clock maintains a 64-bit counter that increments for each frame drawn.
See also:
#2025-3-1
Function gdk:frame-clock-history-start (clock)
Arguments:
clock -- a gdk:frame-clock object
Returns:
The unsigned integer for the frame counter value of the oldest frame that is available in the internal frame history of the frame clock.
Details:
The frame clock internally keeps a history of gdk:frame-timings objects for recent frames that can be retrieved with the gdk:frame-clock-timings function. The set of stored frames is the set from the counter values given by the gdk:frame-clock-history-start function and the gdk:frame-clock-frame-counter function, inclusive.
See also:
#2025-3-1
Function gdk:frame-clock-timings (clock counter)
Arguments:
clock -- a gdk:frame-clock object
counter -- an unsigned integer for the frame counter value identifying the frame to be received
Returns:
The gdk:frame-timings instance for the specified frame, or nil if it is not available. See the gdk:frame-clock-history-start function.
Details:
Retrieves a gdk:frame-timings instance holding timing information for the current frame or a recent frame. The gdk:frame-timings instance may not yet be complete. See the gdk:frame-timings-complete function.
See also:
#2025-3-1
Function gdk:frame-clock-current-timings (clock)
Arguments:
clock -- a gdk:frame-clock object
Returns:
The gdk:frame-timings instance for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been procesed, returns nil.
Details:
Gets the frame timings for the current frame.
See also:
#2025-3-1
Function gdk:frame-clock-refresh-info (clock time)
Arguments:
clock -- a gdk:frame-clock object
time -- an integer for the base time for determining a presentaton time
Returns:
refresh-interval -- an integer with the determined refresh interval, or nil, a default refresh interval of 1/60th of a second will be stored if no history is present
presentation-time -- an integer with the next candidate presentation time after the given base time, 0 will be will be stored if no history is present
Details:
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 time.
See also:
#2025-3-1
Function gdk:frame-clock-fps (clock)
Arguments:
clock -- a gdk:frame-clock object
Returns:
The double float with the current fps.
Details:
Calculates the current frames-per-second, based on the frame timings of clock.
See also:
2025-3-1

Pixbuf, Pango, and Backends interaction

Introduction to GdkPixbuf Interaction

Pixbufs are client-side images. For details on how to create and manipulate pixbufs, see the GdkPixbuf API documentation. The functions described here allow to obtain pixbufs from GdkSurfaces and Cairo surfaces.

Functions for GDKPixbuf Interaction

Function gdk:pixbuf-from-surface (surface xsrc ysrc width height)
Arguments:
surface -- a cairo:surface-t instance to copy from
xsrc -- an integer with the source x coordinate within surface
ysrc -- an integer with the source y coordinate within surface
width -- an integer with the width in pixels of region to get
height -- an integer with the height in pixels of region to get
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil on error.
Details:
Transfers image data from a cairo:surface-t instance and converts it to an RGB(A) representation inside a gdk-pixbuf:pixbuf object. This allows you to efficiently read individual pixels from Cairo surfaces.

This function will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the surface contains one.
Warning:
This function is deprecated since 4.12. Use the gdk:texture class and subclasses instead of Cairo surfaces and pixbufs.
See also:
2024-7-16
Function gdk:pixbuf-from-texture (texture)
Arguments:
texture -- a gdk:texture object
Returns:
The new gdk-pixbuf:pixbuf object, or nil on error.
Details:
Creates a new gdk-pixbuf:pixbuf object from texture. This should generally not be used in newly written code as later stages will almost certainly convert the pixbuf back into a texture to draw it on screen.
Warning:
This function is deprecated since 4.12. Use the gdk:texture class and subclasses instead of Cairo surfaces and pixbufs.
See also:
2024-7-16

Introduction to Pango Interaction

Pango is the text layout system used by GDK and GTK. The functions and types in this section are used to obtain clip regions for Pango Layouts, and to get pango:context objects that can be used with GDK.

Creating a pango:layout object is the first step in rendering text, and requires getting a handle to a pango:context object. For GTK programs, you will usually want to use the gtk:widget-pango-context function, or the gtk:widget-create-pango-layout function. Once you have a pango:layout object, you can set the text and attributes of it with Pango functions like the pango:layout-text function and get its size with the pango:layout-size function. Note that Pango uses a fixed point system internally, so converting between Pango units and pixels using the pango:+scale+ value or the pango:pixels function.

Rendering a Pango layout is done most simply with the pango:cairo-show-layout function. You can also draw pieces of the layout with the pango:cairo-show-layout-line function.

Functions for Pango Interaction

Function gdk:pango-layout-clip-region (layout xorigin yorigin ranges)
Arguments:
layout -- a pango:layout object
xorigin -- an integer with the x pixel where you intend to draw the layout with this clip
yorigin -- an integer with the y pixel where you intend to draw the layout with this clip
ranges -- a list of integer with the byte indexes into the layout, where even members of the list are start indexes and odd elements end indexes
Returns:
The cairo:region-t instance with the clip region containing the given ranges.
Details:
Obtains a clip region which contains the areas where the given ranges of text would be drawn. The xorigin and yorigin arguments are the top left point to center the layout. The ranges argument should contain ranges of bytes in the text of the layout.

Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn layout may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected.
See also:
#2024-7-16
Function gdk:pango-layout-line-clip-region (line xorigin yorigin ranges)
Arguments:
line -- a pango:layout-line instance
xorigin -- an integer with the x pixel where you intend to draw the layout line with this clip
yorigin -- an integer with the y pixel where you intend to draw the layout line with this clip
ranges -- a list of integer with the byte indexes into the layout, where even members of the list are start indexes and odd elements end indexes
Returns:
The cairo:region-t instance with the clip region containing the given ranges.
Details:
Obtains a clip region which contains the areas where the given ranges of text would be drawn. The xorigin and yorigin arguments are the top left position of the layout. The ranges argument should contain ranges of bytes in the text of the layout. The clip region will include space to the left or right of the line (to the layout bounding box) if you have indexes above or below the indexes contained inside the line. This is to draw the selection all the way to the side of the layout. However, the clip region is in line coordinates, not layout coordinates.

Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn layout may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected.
See also:
#2024-7-16

Introduction to Cairo Interaction

Functions to support using Cairo. GDK does not wrap the Cairo API, instead it allows to create Cairo contexts which can be used to draw on GdkSurfaces. Additional functions allow to use GdkRectangles with Cairo and to use GdkRGBAs, GdkPixbufs and GdkSurfaces as sources for drawing operations.

Functions for Cairo Interaction

Function gdk:cairo-set-source-rgba (cr rgba)
Arguments:
cr -- a cairo:context-t instance
rgba -- a gdk:rgba color
Details:
Sets the specified rgba color as the source color of the Cairo context.
Examples:
This code fragment from the GTK Demo sets a draw function for a gtk:drawing-area widget. The color is parsed to a gdk:rgba color and then set as the source color for the cairo:paint operation on the Cairo context.
(gtk:drawing-area-set-draw-func area
        (lambda (widget cr width height)
          (declare (ignore widget width height))
          (let ((rgba (gdk:rgba-parse color)))
            (when rgba
              (gdk:cairo-set-source-rgba cr rgba)
              (cairo:paint cr)))))    
See also:
2024-6-30
Function gdk:cairo-set-source-pixbuf (cr pixbuf x y)
Arguments:
cr -- a cairo:context-t instance
pixbuf -- a gdk-pixbuf:pixbuf object
x -- a number coerced to a double float with the x coordinate to place upper left corner of pixbuf
y -- a number coerced to a double float with the y coordinate to place upper left corner of pixbuf
Details:
Sets the given pixbuf as the source pattern for cr. The pattern has a :none extend mode of the cairo:extend-t enumeration and is aligned so that the origin of the pixbuf is (x,y).
See also:
#2024-7-16
Function gdk:cairo-rectangle (cr rectangle)
Arguments:
cr -- a cairo:context-t instance
rectangle -- a gdk:rectangle instance
Details:
Adds the given rectangle to the current path of cr.
See also:
#2024-7-16
Function gdk:cairo-region (cr region)
Arguments:
cr -- a cairo:context-t instance
region -- a cairo:region-t instance
Details:
Adds the given region to the current path of cr.
See also:
#2024-7-16
Function gdk:cairo-region-create-from-surface (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:region-t instance, must be freed with the cairo:region-destroy function.
Details:
Creates region that describes covers the area where the given surface is more than 50% opaque. This function takes into account device offsets that might be set with the (setf cairo:surface-device-offset) function.
See also:
#2024-7-16
Function gdk:cairo-draw-from-gl (cr surface source type scale x y width height)
Arguments:
cr -- a cairo:context-t instance
surface -- a gdk:surface object that is being rendered for, not necessarily into
source -- an integer for the GL ID of the source buffer
type -- an integer for the type of the source
scale -- an integer for the scale factor that the source buffer is allocated for
x -- an integer for the source x position in source to start copying from in GL coordinates
y -- an integer for the source y position in source to start copying from in GL coordinates
width -- an integer for the width of the region to draw
height -- an integer for the height of the region to draw
Details:
This is the main way to draw GL content in GTK. It takes a render buffer ID (type == GL_RENDERBUFFER) or a texture ID (type == GL_TEXTURE) and draws it onto cr with an OVER operation, respecting the current clip. The top left corner of the rectangle specified by x, y, width and height will be drawn at the current (0,0) position of the Cairo context.

This will work for all Cairo contexts, as long as surface is realized, but the fallback implementation that reads back the pixels from the buffer may be used in the general case. In the case of direct drawing to a surface with no special effects applied to cr it will however use a more efficient approach.

For GL_RENDERBUFFER the code will always fall back to software for buffers with alpha components, so make sure you use GL_TEXTURE if using alpha.

Calling this may change the current GL context.
Warning:
This function is deprecated since 4.6. The function is overly complex and produces broken output in various combinations of arguments. If you want to draw with GL textures in GTK, use the gdk:gl-texture-new function. If you want to use that texture in Cairo, use the gdk:texture-download function to download the data into a Cairo image surface.
See also:
#2025-1-25

Package gsk

GTK Scene Graph Kit (GSK) is the rendering and scene graph API for GTK introduced with version 3.90. GSK lies between the graphical control elements (widgets) and the rendering. Like GDK, GSK is part of GTK and licensed under the GNU Lesser General Public License (LGPL). This is the API documentation of a Lisp binding to GSK.

GskRenderer

Class gsk:renderer
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
realized
The realized property of type :boolean (Read)
Whether the renderer has been associated with a surface or draw context.
Default value : false
surface
The surface property of type gdk:surface (Read)
The surface associated with the renderer.
Returned by:
Slot Access Functions:
Details:
The gsk:renderer class is a class that renders a scene graph defined by a tree of gsk:render-node instances. Typically you will use a gsk:renderer instance to repeatedly call the gsk:renderer-render function to update the contents of its associated gdk:surface object.

It is necessary to realize a gsk:renderer instance using the gsk:renderer-realize function before calling the gsk:renderer-render function, in order to create the appropriate windowing system resources needed to render the scene.
See also:
2024-11-7
Accessor gsk:renderer-realized (object)
Syntax:
(gsk:renderer-realized object) => realized
Arguments:
object -- a gsk:renderer instance
realized -- a boolean whether the renderer has been associated with a surface or draw context
Details:
Accessor of the realized slot of the gsk:renderer class.
See also:
2024-11-7
Accessor gsk:renderer-surface (object)
Syntax:
(gsk:renderer-surface object) => surface
Arguments:
object -- a gsk:renderer instance
surface -- a gdk:surface object
Details:
Accessor of the surface slot of the gsk:renderer class. The gsk:renderer-surface function retrieves the gdk:surface object set using the gsk:renderer-realize function. If the renderer has not been realized yet, nil will be returned.
See also:
2024-11-7
Function gsk:renderer-new-for-surface (surface)
Arguments:
surface -- a gdk:surface object
Returns:
The new gsk:renderer instance.
Details:
Creates an appropriate gsk:renderer instance for the given surface. If the GSK_RENDERER environment variable is set, GSK will try that renderer first, before trying the backend-specific default. The ultimate fallback is the Cairo renderer.

The renderer will be realized before it is returned.
See also:
2024-11-7
Function gsk:renderer-realize (renderer surface)
Arguments:
renderer -- a gsk:renderer instance
surface -- a gdk:surface object
Details:
Creates the resources needed by the renderer to render the scene graph.
See also:
#2024-11-21
Function gsk:renderer-unrealize (renderer)
Arguments:
renderer -- a gsk:renderer instance
Details:
Releases all the resources created by the gsk:renderer-realize function.
See also:
#2024-11-7
Function gsk:renderer-is-realized (renderer)
Arguments:
renderer -- a gsk:renderer instance
Returns:
True if renderer was realized, and false otherwise.
Details:
Checks whether the renderer is realized or not.
See also:
2024-11-7
Function gsk:renderer-render (renderer root &optional region)
Arguments:
renderer -- a gsk:renderer instance
root -- a gsk:render-node instance
region -- an optional cairo:context-t instance with the region that must be redrawn or the default nil value for the whole window
Details:
Renders the scene graph, described by a tree of gsk:render-node instances, ensuring that the given region gets redrawn. Renderers must ensure that changes of the contents given by the root node as well as the area given by region are redrawn. They are however free to not redraw any pixel outside of region if they can guarantee that it did not change.

The renderer will acquire a reference on the gsk:render-node tree while the rendering is in progress.
See also:
#2024-11-7
Function gsk:renderer-render-texture (renderer root &optional viewport)
Arguments:
renderer -- a gsk:renderer instance
root -- a gsk:render-node instance
viewport -- an optional graphene:rect-t instance with the section to draw or the default nil value to use the bounds of root
Returns:
The gdk:texture instance with the rendered contents of root.
Details:
Renders the scene graph, described by a tree of gsk:render-node instances, to a gdk:texture instance. The renderer will acquire a reference on the gsk:render-node tree while the rendering is in progress.

If you want to apply any transformations to root, you should put it into a transform node and pass that node instead.
See also:
#2024-11-7
Class gsk:cairo-renderer
Superclasses:
gsk:renderer, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The GSK renderer that is using Cairo. Since the renderer is using Cairo, this renderer cannot support 3D transformations.
See also:
2024-11-7
Function gsk:cairo-renderer-new ()
Returns:
The new Cairo gsk:renderer instance.
Details:
Creates a new gsk:renderer instance using Cairo. The Cairo renderer is the fallback renderer drawing in ways similar to how GTK 3 drew its content. Its primary use is as comparison tool.

The Cairo renderer is incomplete. It cannot render 3D transformed content and will instead render an error marker. Its usage should be avoided.
See also:
2024-11-7
Class gsk:gl-renderer
Superclasses:
gsk:renderer, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The OpenGL based renderer. See the gsk:renderer documentation.

Since 4.2
See also:
2024-11-7
Function gsk:gl-renderer-new ()
Returns:
The new OpenGL gsk:renderer instance.
Details:
Creates a new gsk:renderer instance using OpenGL. This is the default renderer used by GTK.
See also:
2024-11-7
Class gsk:ngl-renderer
Superclasses:
gsk:renderer, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The new experimental OpenGL based renderer. See the gsk:renderer documentation.

Since 4.2
See also:
2024-11-7
Function gsk:ngl-renderer-new ()
Returns:
The new experimental OpenGL gsk:renderer instance.
Details:
Creates an instance of the new experimental OpenGL renderer.
See also:
2024-11-7

GskPathMeasure

GBoxed gsk:path-measure
Declaration:
(glib:define-gboxed-opaque path-measure "GskPathMeasure"
  :export t
  :type-initializer "gsk_path_measure_get_type"
  :alloc (error "GSK:PATH-MEASURE cannot be created from the Lisp side"))  
Returned by:
Details:
The gsk:path-measure structure is a structure that allows measurements on gsk:path intances such as determining the length of the path. Many measuring operations require sampling the path length at intermediate points. Therefore, a gsk:path-measure instance has a tolerance that determines what precision is required for such approximations.

Since 4.14
See also:
2024-11-8
Function gsk:path-measure-new (path)
Arguments:
path -- a gsk:path instance with the path to measure
Returns:
The new gsk:path-measure instance representing path.
Details:
Creates a measure object for the given path with the default tolerance.

Since 4.14
See also:
2024-11-8
Function gsk:path-measure-new-with-tolerance (path tolerance)
Arguments:
path -- a gsk:path instance with the path to measure
tolerance -- a number coerced to a float with the tolerance for measuring operations
Returns:
The new gsk:path-measure instance representing path.
Details:
Creates a measure object for the given path and tolerance.

Since 4.14
See also:
2024-11-8
Function gsk:path-measure-length (measure)
Arguments:
measure -- a gsk:path-measure instance
Returns:
The float with the length of the path measured by measure.
Details:
Gets the length of the path being measured. The length is cached, so this function does not do any work.

Since 4.14
See also:
2024-11-8
Function gsk:path-measure-path (measure)
Arguments:
measure -- a gsk:path-measure instance
Returns:
The gsk:path instance of measure.
Details:
Returns the path that the measure was created for.

Since 4.14
See also:
2024-11-8
Function gsk:path-measure-point (measure distance)
Arguments:
measure -- a gsk:path-measure instance
distance -- a number coerced to a float with the distance
Details:
Returns the point at the given distance into the path. An empty path has no points, so nil is returned in that case.

Since 4.14
See also:
2024-11-9
Function gsk:path-measure-tolerance (measure)
Arguments:
measure -- a gsk:path-measure instance
Returns:
The float with the tolerance of measure
Details:
Returns the tolerance that the measure was created with.

Since 4.14
See also:
2024-11-9

GtkPathPoint

GEnum gsk:path-direction
Declaration:
(gobject:define-genum "GskPathDirection" path-direction
  (:export t
   :type-initializer "gsk_path_direction_get_type")
  :from-start
  :to-start
  :to-end
  :from-end)  
Values:
:from-start
The tangent in path direction of the incoming side of the path.
:to-start
The tangent against path direction of the incoming side of the path.
:to-end
The tangent in path direction of the outgoing side of the path.
:from-end
The tangent against path direction of the outgoing side of the path.
Details:
The values of the gsk:path-direction enumeration are used to pick one of the four tangents at a given point on the path. Note that the directions for :from-start/:to-end and :to-start/:from-end will coincide for smooth points. Only sharp turns will exhibit four different directions.

Figure: GtkPathDirection

Since 4.14
See also:
2024-11-9
GBoxed gsk:path-point
Declaration:
(glib:define-gboxed-opaque path-point "GskPathPoint"
  :export t
  :type-initializer "gsk_path_point_get_type"
  :alloc (error "GSK:PATH-POINT cannot be created from the Lisp side"))  
Returned by:
Details:
The gsk:path-point structure is an opaque type representing a point on a path. It can be queried for properties of the path at that point, such as its tangent or its curvature.

To obtain a gsk:path-point instance, use the gsk:path-closest-point, gsk:path-start-point, gsk:path-end-point or gsk:path-measure-point functions.

Note that gsk:path-point instances are meant to be stack-allocated, and do not hold a reference to the path object they are obtained from. It is the callers responsibility to keep a reference to the path as long as the gsk:path-point instance is used.

Since 4.14
See also:
2024-11-7
Function gsk:path-point-curvature (point path direction center)
Arguments:
point -- a gsk:path-point instance
path -- a gsk:path instance with the path that point is on
direction -- a gsk:path-direction value with the direction for which to return the curvature
center -- a graphene:point-t instance which will be set with the center of the osculating circle
Returns:
The float with the curvature of the path at the given point.
Details:
Calculates the curvature of the path at the point. Returns the center of the osculating circle as well. The curvature is the inverse of the radius of the osculating circle.

Lines have a curvature of zero, indicating an osculating circle of infinite radius. In this case, the center is not modified. Circles with a radius of zero have INFINITY as curvature.

Note that certain points on a path may not have a single curvature, such as sharp turns. At such points, there are two curvatures - the limit of the curvature of the path going into the point, and the limit of the curvature of the path coming out of it. The direction argument lets you choose which one to get.

Figure: Curvature at point
See also:
2024-11-9
Function gsk:path-point-distance (point measure)
Arguments:
point -- a gsk:path-point instance
measure -- a gsk:path-measure instance for the path
Returns:
The float with the distance of point.
Details:
Returns the distance from the beginning of the path to point.

Since 4.14
See also:
#2024-11-9
Function gsk:path-point-position (point path pos)
Arguments:
point -- a gsk:path-point instance
path -- a gsk:path instance with the path point is on
pos -- a graphene:point-t instance for the coordinates of the point
Returns:
The graphene:point-t instance.
Details:
Gets the position of the point.

Since 4.14
See also:
#2024-11-9
Function gsk:path-point-rotation (point path direction)
Arguments:
point -- a gsk:path-point instance
path -- a gsk:path instance with the path that point is on
direction -- a gsk:path-direction value with the direction for which to return the rotation
Returns:
The float with the angle between the tangent and the X axis, in degrees.
Details:
Gets the direction of the tangent at a given point. This is a convenience variant of the gsk:path-point-tangent function that returns the angle between the tangent and the X axis. The angle can, for example, be used in the gtk:snapshot-rotate function.

Since 4.14
See also:
#2024-11-9
Function gsk:path-point-tangent (point path direction tangent)
Arguments:
point -- a gsk:path-point instance
path -- a gsk:path instance with the path that point is on
direction -- a gsk:path-direction value with the direction for which to return the tangent
tangent -- a graphene:vec2-t instance for the tangent at the point
Returns:
The graphene:vec2-t instance.
Details:
Gets the tangent of the path at the point. Note that certain points on a path may not have a single tangent, such as sharp turns. At such points, there are two tangents - the direction of the path going into the point, and the direction coming out of it. The direction argument lets you choose which one to get.

If the path is just a single point, for example, a circle with radius zero, then tangent is set to 0, 0.

If you want to orient something in the direction of the path, the gsk:path-point-rotation function may be more convenient to use.

Since 4.14
See also:
#2024-11-9
Function gsk:path-point-compare (point1 point2)
Arguments:
point1 -- a gsk:path-point instance
point2 -- another gsk:path-point instance
Returns:
The integer which is -1 if point1 is before point2, 1 if point1 is after point2, 0 if they are equal.
Details:
Returns whether point1 is before or after point2.

Since 4.14
See also:
#2024-11-9
Function gsk:path-point-copy (point)
Arguments:
point -- a gsk:path-point instance
Returns:
The copied gsk:path-point instance.
Details:
Copies a path point.
See also:
#2024-11-9
Function gsk:path-point-equal (point1 point2)
Arguments:
point1 -- a gsk:path-point instance
point2 -- another gsk:path-point instance
Returns:
True if point1 and point2 are equal.
Details:
Returns whether the two path points refer to the same location on all paths. Note that the start and end point of a closed contour will compare nonequal according to this definition. Use the gsk:path-is-closed function to find out if the start and end point of a concrete path refer to the same location.

Since 4.14
See also:
#2024-11-9

GskStroke

GEnum gsk:line-cap
Declaration:
(gobject:define-genum "GskLineCap" line-cap
  (:export t
   :type-initializer "gsk_line_cap_get_type")
  :butt
  :round
  :square)  
Values:
:butt
Start and stop the line exactly at the start and end point.
:round
Use a round ending, the center of the circle is the start or end point.
:square
Use squared ending, the center of the square is the start or end point.
Details:
Specifies how to render the start and end points of contours or dashes when stroking. The default line cap style is :butt.

Figure: GskLineCap

Since 4.16
See also:
2024-11-9
GEnum gsk:line-join
Declaration:
(gobject:define-genum "GskLineJoin" line-join
  (:export t
   :type-initializer "gsk_line_join_get_type")
  :miter
  :round
  :bevel)  
Values:
:miter
Use a sharp angled corner.
:round
Use a round join, the center of the circle is the join point.
:bevel
Use a cut-off join, the join is cut off at half the line width from the joint point.
Details:
Specifies how to render the junction of two lines when stroking. The default line join style is :miter.

Figure: GskLineJoin

Since 4.14
See also:
2024-11-9
GBoxed gsk:stroke
Declaration:
(glib:define-gboxed-opaque stroke "GskStroke"
  :export t
  :type-initializer "gsk_stroke_get_type"
  :alloc (error "GSK:STROKE cannot be created from the Lisp side"))  
Returned by:
Details:
The gsk:stroke structure collects the parameters that influence the operation of stroking a path.

Since 4.14
See also:
2024-11-9
Function gsk:stroke-new (width)
Arguments:
width -- a number coerced to a single float for the line width of the stroke, must be > 0
Returns:
The new gsk:stroke instance.
Details:
Creates a new gsk:stroke instance with the given width.

Since 4.14
See also:
2025-3-1
Function gsk:stroke-copy (stroke)
Arguments:
stroke -- a gsk:stroke instance
Returns:
The new gsk:stroke instance.
Details:
Creates a copy of the given stroke.
See also:
#2024-11-11
Function gsk:stroke-equal (stroke1 stroke2)
Arguments:
stoke1 -- a gsk:stroke instance
stoke2 -- another gsk:stroke instance
Returns:
True if the two strokes are equal, false otherwise.
Details:
Checks if two strokes are identical.
See also:
#2024-11-11
Function gsk:stroke-dash (stroke)
Syntax:
(gsk:stroke-dash stroke) => dash
(setf (gsk:stroke-dash stroke) dash)
Arguments:
stroke -- a gsk:stroke instance
dash -- a list of numbers coerced to floats with the dashes
Details:
The gsk:stroke-dash function gets the list of dashes in use or nil if dashing is disabled. The (setf gsk:stroke-dash) funtion sets the dash pattern to use by the stroke.

A dash pattern is specified by a list of alternating non-negative values. Each value provides the length of alternate 'on' and 'off' portions of the stroke. Each 'on' segment will have caps applied as if the segment were a separate contour. In particular, it is valid to use an 'on' length of 0 with :round or :square to draw dots or squares along a path.

If dash is empty, if all elements in dash are 0, or if there are negative values in dash, then dashing is disabled. If dash has one element, an alternating 'on' and 'off' pattern with the single dash length provided is assumed. If dash has uneven elements, the dash list will be used with the first element in dash defining an 'on' or 'off' in alternating passes through the list.

You can specify a starting offset into the dash with the gsk:stroke-dash-offset function.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-dash-offset (stroke)
Syntax:
(gsk:stroke-dash-offset stroke) => offset
(setf (gsk:stroke-dash-offset stroke) offset)
Arguments:
stroke -- a gsk:stroke instance
offset -- a number coerced to a float with the offset into the dash pattern
Details:
The gsk:stroke-dash-offset function returns the dash offset of a gsk:stroke instance. The (setf gsk:stroke-dash-offset) function sets the offset into the dash pattern where dashing should begin.

This is an offset into the length of the path, not an index into the list values of the dash list. See the gsk:stroke-dash function for more details on dashing.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-line-cap (stroke)
Syntax:
(gsk:stroke-line-cap stroke) => cap
(setf (gsk:stroke-line-cap stroke) cap)
Arguments:
stroke -- a gsk:stroke instance
cap -- a gsk:line-cap value
Details:
The gsk:stroke-line-cap function gets the line cap used. The (setf gsk:stroke-line-cap) functionsets the line cap to be used when stroking. See the gsk:line-cap documentation for details.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-line-join (stroke)
Syntax:
(gsk:stroke-line-join stroke) => join
(setf (gsk:stroke-line-join stroke) join)
Arguments:
stroke -- a gsk:stroke instance
join -- a gsk:line-join value
Details:
The gsk:stroke-line-join function gets the line join used. The (setf gsk:stroke-line-join) function sets the line join to be used when stroking. See the gsk:line-join documentation for details.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-line-width (stroke)
Syntax:
(gsk:stroke-line-width stroke) => width
(setf (gsk:stroke-line-width stroke) width)
Arguments:
stroke -- a gsk:stroke instance
width -- a number coerced to a float with the width of the line in pixels
Details:
The gsk:stroke-line-width function gets the line width used. The (setf gsk:stroke-line-width) function sets the line width to be used when stroking. The line width must be > 0.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-miter-limit (stroke)
Syntax:
(gsk:stroke-miter-limit stroke) => limit
(setf (gsk:stroke-miter-limit stroke) limit)
Arguments:
stroke -- a gsk:stroke instance
limit -- a number coerced to a float with the miter limit
Details:
The gsk:stroke-miter-limit function returns the miter limit of a gsk:stroke instance. The (setf gsk:stroke-miter-limit) function sets the limit for the distance from the corner where sharp turns of joins get cut off.

The miter limit is in units of line width and must be non-negative. For joins of type :miter that exceed the miter limit, the join gets rendered as if it was of the :bevel type.

Since 4.14
See also:
#2024-11-11
Function gsk:stroke-to-cairo (stroke context)
Arguments:
stroke -- a gsk:stroke instance
context -- a cairo:context-t instance to configure
Details:
A helper function that sets the stroke parameters of context from the values found in stroke.

Since 4.14
See also:
#2024-11-11

GskPath

GFlags gsk:path-foreach-flags
Declaration:
(gobject:define-gflags "GskPathForeachFlags" path-foreach-flags
  (:export t
   :type-initializer "gsk_path_foreach_flags_get_type")
  (:allow-only-lines 0)
  (:allow-quad #.(ash 1 0))
  (:allow-cubic #.(ash 1 1))
  (:allow-conic #.(ash 1 2)))  
Values:
:allow-only-lines
The default behavior, only allow lines.
:allow-quad
Allow emission of :quad operations.
:allow-cubic
Allow emission of :cubic operations.
:allow-conic
Allow emission of :conic operations.
Details:
Flags that can be passed to the gsk:path-foreach function to influence what kinds of operations the path is decomposed into. By default, the gsk:path-foreach function will only emit a path with all operations flattened to straight lines to allow for maximum compatibility. The only operations emitted will be :move, :line and :close.

Since 4.14
See also:
2024-11-9
GEnum gsk:path-operation
Declaration:
(gobject:define-genum "GskPathOperation" path-operation
  (:export t
   :type-initializer "gsk_path_operation_get_type")
  :move
  :close
  :line
  :quad
  :cubic
  :conic)  
Values:
:move
A move-to operation, with 1 point describing the target point.
:close
A close operation ending the current contour with a line back to the starting point. Two points describe the start and end of the line.
:line
A line-to operation, with 2 points describing the start and end point of a straight line.
:quad
A curve-to operation describing a quadratic Bézier curve with 3 points describing the start point, the control point and the end point of the curve.
:cubic
A curve-to operation describing a cubic Bézier curve with 4 points describing the start point, the two control points and the end point of the curve.
:conic
A rational quadratic Bézier curve with 3 points describing the start point, control point and end point of the curve. A weight for the curve will be passed, too.
Details:
Path operations are used to describe the segments of a gsk:path instance.

Since 4.14
See also:
2024-11-9
GEnum gsk:fill-rule
Declaration:
(gobject:define-genum "GskFillRule" fill-rule
  (:export t
   :type-initializer "gsk_fill_rule_get_type")
  :winding
  :even-odd)  
Values:
:winding
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.
:even-odd
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.
Details:
The gsk:fill-rule enumeration is used to select how paths are filled. Whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it does not 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.

Since 4.14
See also:
2024-11-9
GBoxed gsk:path
Declaration:
(glib:define-gboxed-opaque path "GskPath"
  :export t
  :type-initializer "gsk_path_get_type"
  :alloc (error "GSK:PATH cannot be created from the Lisp side"))  
Details:
A gsk:path structure describes lines and curves that are more complex than simple rectangles. Paths can used for rendering (filling or stroking) and for animations, for eample as trajectories.

The gsk:path structure is an immutable, opaque, reference-counted structure. After creation, you cannot change the types it represents. Instead, new gsk:path instances have to be created. The gsk:path-builder structure is meant to help in this endeavor.

Conceptually, a path consists of zero or more contours (continuous, connected curves), each of which may or may not be closed. Contours are typically constructed from Bézier segments.

Figure: GskPath

Since 4.14
See also:
2024-11-9
Function gsk:path-parse (str)
Arguments:
str -- a string
Details:
This is a convenience function that constructs a gsk:path instance from a serialized form. The string is expected to be in (a superset of) SVG path syntax, as, for example, produced by the gsk:path-to-string function.

A high-level summary of the syntax:
M x y
Move to (x,y)
L x y
Add a line from the current point to (x,y)
Q x1 y1 x2 y2
Add a quadratic Bézier from the current point to (x2,y2), with control point (x1,y1)
C x1 y1 x2 y2 x3 y3
Add a cubic Bézier from the current point to (x3,y3), with control points (x1,y1) and (x2,y2)
Z
Close the contour by drawing a line back to the start point
H x
Add a horizontal line from the current point to the given x value
V y
Add a vertical line from the current point to the given y value
T x2 y2
Add a quadratic Bézier, using the reflection of the previous segments’ control point as control point
S x2 y2 x3 y3
Add a cubic Bézier, using the reflection of the previous segments’ second control point as first control point
A rx ry r l s x y
Add an elliptical arc from the current point to (x,y) with radii rx and ry. See the SVG documentation for how the other parameters influence the arc.
O x1 y1 x2 y2 w
Add a rational quadratic Bézier from the current point to (x2,y2) with control point (x1,y1) and weight w.
All the commands have lowercase variants that interpret coordinates relative to the current point. The O command is an extension that is not supported in SVG.

Since 4.14
See also:
#2024-11-11
Callback gsk:path-foreach-func
Syntax:
lambda (operation points n-points weight)
Arguments:
operation -- a gsk:path-operation value
points -- an array of graphene:point-t instances
n-points -- an integer with the points of the operation
weight -- a float with the weight for conic curves, or unused if not a conic curve
Details:
Prototype of the callback function to iterate through the operations of a path. For each operation, the callback function is given operation itself, the points that the operation is applied to in points, and a weight for conic curves. The n-points argument is somewhat redundant, since the number of points can be inferred from the operation.

Each contour of the path starts with a :move operation. Closed contours end with a :close operation.

Since 4.14
See also:
#2024-11-12
Function gsk:path-foreach (path flags func)
Arguments:
path -- a gsk:path instance
flags -- a gsk:path-foreach-flags value with the flags to pass to func
func -- a gsk:path-foreach-func callback function
Returns:
False if func returned false, true otherwise
Details:
Calls func for every operation of the path. Note that this may only approximate path, because paths can contain optimizations for various specialized contours, and depending on the flags, the path may be decomposed into simpler curves than the ones that it contained originally.

This function serves two purposes:
  • When the flags allow everything, it provides access to the raw, unmodified data of the path.
  • When the flags disallow certain operations, it provides an approximation of the path using just the allowed operations.
Since 4.14
See also:
#2024-11-12
Function gsk:path-bounds (path bounds)
Arguments:
path -- a gsk:path instance
bounds -- a graphene:rect-t instance for the bounds of the given path
Returns:
The graphene:rect-t instance or nil.
Details:
Computes the bounds of the given path. The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the path.

It is possible that the returned rectangle has 0 width and/or height. This can happen when the path only describes a point or an axis-aligned line.

If the path is empty, false is returned and bounds are set to the graphene:rect-zero value. This is different from the case where the path is a single point at the origin, where the bounds will also be set to the zero rectangle but true will be returned.

Since 4.14
See also:
#2024-11-12
Function gsk:path-closest-point (path point threshold)
Syntax:
(gsk:path-closest-point path point threshold) => result, distance
Arguments:
path -- a gsk:path instance
point -- a graphene:point-t instance
threshold -- a float with the maximum allowed distance
Returns:
result -- a gsk:path-point instance with the closest point distance -- a float with the distance
Details:
Computes the closest point on the path to the given point and sets the result to it. If there is no point closer than the given threshold, nil is returned.

Since 4.14
See also:
2024-11-12
Function gsk:path-start-point (path)
Arguments:
path -- a gsk:path instance
Returns:
The gsk:path-point instance with the point.
Details:
Gets the start point of the path. An empty path has no points, so nil is returned in this case.

Since 4.14
See also:
gsk:path
gsk:path-pointer
2024-11-12
Function gsk:path-end-point (path)
Arguments:
path -- a gsk:path instance
Returns:
The gsk:path-point instance with the point.
Details:
Gets the end point of the path. An empty path has no points, so nil is returned in this case.

Since 4.14
See also:
gsk:path
gsk:path-pointer
2024-11-12
Function gsk:path-stroke-bounds (path stroke bounds)
Arguments:
path -- a gsk:path instance
stroke -- a gsk:stroke instance with the stroke parameters
bounds -- a graphene:rect-t instance with the bounds to fill in
Returns:
The graphene:rect-t instance with the bounds, or nil.
Details:
Computes the bounds for stroking the given path with the parameters in stroke. The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the area affected by the stroke, including protrusions like miters.

Since 4.14
See also:
#2024-11-12
Function gsk:path-in-fill (path point rule)
Arguments:
path -- a gsk:path instance
point -- a graphene:point-t instance with the point to test
rule -- a gsk:fill-rule value
Returns:
True if point is inside.
Details:
Returns whether the given point is inside the area that would be affected if the path was filled according to rule. Note that this function assumes that filling a contour implicitly closes it.

Since 4.14
See also:
#2024-11-12
Function gsk:path-is-closed (path)
Arguments:
path -- a gsk:path instance
Returns:
True if the path is closed.
Details:
Returns if the path represents a single closed contour.

Since 4.14
See also:
#2024-11-12
Function gsk:path-is-empty (path)
Arguments:
path -- a gsk:path instance
Returns:
True if the path is empty.
Details:
Checks if the path is empty, that is, contains no lines or curves.

Since 4.14
See also:
#2024-11-12
Function gsk:path-to-cairo (path context)
Arguments:
path -- a gsk:path instance
context -- a cairo:context-t instance
Details:
Appends the given path to the given Cairo context for drawing with Cairo. This may cause some suboptimal conversions to be performed as Cairo does not support all features of the gsk:path instance.

This function does not clear the existing Cairo path. Call the cairo:new-path function if you want this.

Since 4.14
See also:
#2024-11-12
Function gsk:path-to-string (path)
Arguments:
path -- a gsk:path instance
Returns:
The string for path.
Details:
Converts the path into a human-readable string representation suitable for printing. The string is compatible with a superset of the SVG path syntax. See the gsk:path-parse function for a summary of the syntax.

Since 4.14
See also:
#2024-11-12

GskPathBuilder

GBoxed gsk:path-builder
Declaration:
(glib:define-gboxed-opaque path-builder "GskPathBuilder"
  :export t
  :type-initializer "gsk_path_builder_get_type"
  :alloc (%path-builder-new))  
Returned by:
Details:
The gsk:path-builder structure is an auxiliary structure for constructing gsk:path instances.

A path is constructed like this:
GskPath *
construct_path (void)
{
  GskPathBuilder *builder;

builder = gsk_path_builder_new ();

// add contours to the path here

return gsk_path_builder_free_to_path (builder);
Adding contours to the path can be done in two ways. The easiest option is to use the gsk:path-builder_add-* group of functions that add predefined contours to the current path, either common shapes like a circle with the gsk:path-builder-add-circle function or by adding from other paths like a path with the gsk:path-builder-add-path function. The gsk:path-builder-add-* methods always add complete contours, and do not use or modify the current point.

The other option is to define each line and curve manually with the gsk:path-builder-*-to group of functions. You start with a call to the gsk:path-builder-move-to function to set the starting point and then use multiple calls to any of the drawing functions to move the pen along the plane. Once you are done, you can call the gsk:path-builder-close function to close the path by connecting it back with a line to the starting point. This is similar to how paths are drawn in Cairo.

Note that the gsk:path-builder instance will reduce the degree of added Bézier curves as much as possible, to simplify rendering.

Since 4.14
See also:
2024-11-12
Function gsk:path-builder-new ()
Returns:
The new gsk:path-builder instance.
Details:
Create a new gsk:path-builder instance. The resulting builder would create an empty gsk:path instance. Use addition functions to add types to it.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-to-path (builder)
Arguments:
builder -- a gsk:path-builder instance
Returns:
The newly created gsk:path instance with all the contours added to the path builder.
Details:
Creates a new gsk:path instance from the given path builder. The given gsk:path-builder instance is reset once this function returns. You cannot call this function multiple times on the same builder instance.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-current-point (path point)
Arguments:
builder -- a gsk:path-builder instance
point -- a graphene:point-t instance for the current point
Returns:
The graphene:point-t instance with the current point.
Details:
Gets the current point. The current point is used for relative drawing commands and updated after every operation.

When the builder is created, the default current point is set to (0, 0). Note that this is different from Cairo, which starts out without a current point.

Since 4.14
See also:
#2024-11-13
Function gsk:path-builder-close (builder)
Arguments:
builder -- a gsk:path-builder instance
Details:
Ends the current contour with a line back to the start point. Note that this is different from calling the gsk:path-builder-line-to function with the start point in that the contour will be closed. A closed contour behaves differently from an open one. When stroking, its start and end point are considered connected, so they will be joined via the line join, and not ended with line caps.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-add-rect (builder rect)
Arguments:
builder -- a gsk:path-builder instance
rect -- a graphene:rect-t instance for the rectangle to create a path for
Details:
Adds rect as a new contour to the path built by the path builder. The path is going around the rectangle in clockwise direction.

If the the width or height are 0, the path will be a closed horizontal or vertical line. If both are 0, it will be a closed dot.

Since 4.14
See also:
2025-1-3
Function gsk:path-builder-add-circle (builder center radius)
Arguments:
builder -- a gsk:path-builder instance
center -- a graphene:point-t instance with the center of the circle
radius -- a number coerced to a single float with the radius of the circle
Details:
Adds a circle with center and radius. The path is going around the circle in clockwise direction. If radius is zero, the contour will be a closed point.

Since 4.14
See also:
2023-11-13
Function gsk:path-builder-add-layout (builder layout)
Arguments:
builder -- a gsk:path-builder instance
layout -- a pango:layout instance with the Pango layout to add
Details:
Adds the outlines for the glyphs in layout to the path builder.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-add-path (builder path)
Arguments:
builder -- a gsk:path-builder instance
path -- a gsk:path instance with the path to append
Details:
Appends all of path to the path builder.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-add-reverse-path (builder path)
Arguments:
builder -- a gsk:path-builder instance
path -- a gsk:path instance with the path to append
Details:
Appends all of path to the path builder, reverse order.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-add-rounded-rect (builder rect)
Arguments:
builder -- a gsk:path-builder instance
rect -- a gsk:rounded-rect instance with the rounded rectangle
Details:
Adds rect as a new contour to the path built in builder. The path is going around the rectangle in clockwise direction.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-add-segment (builder path start end)
Arguments:
builder -- a gsk:path-builder instance
path -- a gsk:path instance with the path to take the segment to
start -- a gsk:path-point instance with the point on path to start at
end -- a gsk:path-point instance with the point on path to end at
Details:
Adds to builder the segment of path from start to end. If start is equal to or after end, the path will first add the segment from start to end of the path, and then add the segment from the beginning to end. If the path is closed, these segments will be connected.

Note that this method always adds a path with the given start point and end point. To add a closed path, use the gsk:path-builder-add-path functin.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-add-cairo-path (builder path)
Arguments:
builder -- a gsk:path-builder instance
context -- a cairo:path-t instance with a path
Details:
Adds a Cairo path to the path builder. You can use the cairo:copy-path function to access the path from a Cairo context.

Since 4.14
See also:
2024-11-13
Function gsk:path-builder-move-to (builder x y)
Arguments:
builder -- a gsk:path-builder instance
x -- a number coerced to a single float with the X coordinate
y -- a number coerced to a single float with the Y coordinate
Details:
Starts a new contour by placing the pen at x, y. If this function is called twice in succession, the first call will result in a contour made up of a single point. The second call will start a new contour.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-move-to (builder x y)
Arguments:
builder -- a gsk:path-builder instance
x -- a number coerced to a single float with the X offset
y -- a number coerced to a single float with the Y offset
Details:
Starts a new contour by placing the pen at x, y relative to the current point. This is the relative version of the gsk:path-builder-move-to function.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-line-to (builder x y)
Arguments:
builder -- a gsk:path-builder instance
x -- a number coerced to a single float with the X coordinate
y -- a number coerced to a single float with the Y coordinate
Details:
Draws a line from the current point to x, y and makes it the new current point.

Figure: Draw line

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-line-to (builder x y)
Arguments:
builder -- a gsk:path-builder instance
x -- a number coerced to a single float with the X offset
y -- a number coerced to a single float with the Y offset
Details:
Draws a line from the current point to a point offset from it by x, y and makes it the new current point. This is the relative version of gsk:path-builder-line-to function. Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-arc-to (builder x1 y1 x2 y2)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
Details:
Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions. After this, x2, y2 will be the new current point.

Note: Two points and their tangents do not determine a unique ellipse, so GSK just picks one. If you need more precise control, use the gsk:path-builder-conic-to or gsk:path-builder-svg-arc-to functions.

Figure: Draw arc

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-arc-to (builder x1 y1 x2 y2)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
Details:
Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-arc-to function.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-conic-to (builder x1 y1 x2 y2 weight)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
weight -- a number coerced to a single float with the weight of the control point, must be greater than zero
Details:
Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point. The weight determines how strongly the curve is pulled towards the control point. A conic with weight 1 is identical to a quadratic Bézier curve with the same points.

Conic curves can be used to draw ellipses and circles. They are also known as rational quadratic Bézier curves.

After this, x2, y2 will be the new current point.

Figure: Draw conic curve

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-conic-to (builder x1 y1 x2 y2 weight)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
weight -- a number coerced to a single float with the weight of the control point, must be greater than zero
Details:
Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-conic-to function.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-cubic-to (builder x1 y1 x2 y2 x3 y3)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
x3 -- a number coerced to a single float with the X coordinate of the end of the curve
y2 -- a number coerced to a single float with the Y coordinate of the end of the curve
Details:
Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points. After this, x3, y3 will be the new current point.

Figure: Draw cubic

See also:
#2024-11-14
Function gsk:path-builder-rel-cubic-to (builder x1 y1 x2 y2 x3 y3)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
x3 -- a number coerced to a single float with the X coordinate of the end of the curve
y3 -- a number coerced to a single float with the Y coordinate of the end of the curve
Details:
Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-cubic-to function.
See also:
#2024-11-14
Function gsk:path-builder-quad-to (builder x1 y1 x2 y2)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the end of the curve
y2 -- a number coerced to a single float with the Y coordinate of the end of the curve
Details:
Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 as the control point. After this, x2, y2 will be the new current point.

Figure: Draw quad

See also:
#2024-11-14
Function gsk:path-builder-rel-quad-to (builder x1 y1 x2 y2)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the end of the curve
y2 -- a number coerced to a single float with the Y coordinate of the end of the curve
Details:
Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 as the control point. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-quad-to function.
See also:
#2024-11-14
Function gsk:path-builder-html-arc-to (builder x1 y1 x2 y2 radius)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
radius -- a number coerced to a single float with the radius of the circle
Details:
Implements arc-to according to the HTML Canvas spec. A convenience function that implements the HTML arc-to functionality.

After this, the current point will be the point where the circle with the given radius touches the line from x1, y1 to x2, y2.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-html-arc-to (builder x1 y1 x2 y2 radius)
Arguments:
builder -- a gsk:path-builder instance
x1 -- a number coerced to a single float with the X coordinate of the first control point
y1 -- a number coerced to a single float with the Y coordinate of the first control point
x2 -- a number coerced to a single float with the X coordinate of the second control point
y2 -- a number coerced to a single float with the Y coordinate of the second control point
radius -- a number coerced to a single float with the radius of the circle
Details:
Implements arc-to according to the HTML Canvas spec. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-html-arc-to function.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-svg-arc-to (builder rx ry x-axis-rotation large-arc positive-sweep x y)
Arguments:
rx -- a number coerced to a single float with the X radius
ry -- a number coerced to a single float with the Y radius
x-axis-rotation -- a number coerced to a single float with the rotation of the ellipsis
large-arc -- whether to add the large arc
positive-sweep -- whether to sweep in the positive direction
x -- a number coerced to a single float with the X coordinate of the end point
y -- a number coerced to a single float with the Y coordinate of the end point
Details:
Implements arc-to according to the SVG spec. A convenience function that implements the SVG arc-to functionality. After this, x, y will be the new current point.

Since 4.14
See also:
#2024-11-14
Function gsk:path-builder-rel-svg-arc-to (builder rx ry x-axis-rotation large-arc positive-sweep x y)
Arguments:
rx -- a number coerced to a single float with the X radius
ry -- a number coerced to a single float with the Y radius
x-axis-rotation -- a number coerced to a single float with the rotation of the ellipsis
large-arc -- whether to add the large arc
positive-sweep -- whether to sweep in the positive direction
x -- a number coerced to a single float with the X coordinate of the end point
y -- a number coerced to a single float with the Y coordinate of the end point
Details:
Implements arc-to according to the SVG spec. All coordinates are given relative to the current point. This is the relative version of the gsk:path-builder-svg-arc-to function.

Since 4.14
See also:
#2024-11-14

GskRenderNode

GEnum gsk:render-node-type
Declaration:
(gobject:define-genum "GskRenderNodeType" render-node-type
  (:export t
   :type-initializer "gsk_render_node_type_get_type")
  :not-a-render-node
  :container-node
  :cairo-node
  :color-node
  :linear-gradient-node
  :repeating-linear-gradient-node
  :radial-gradient-node
  :repeating-radial-gradient-node
  :conic-gradient-node
  :border-node
  :texture-node
  :inset-shadow-node
  :outset-shadow-node
  :transform-node
  :opacity-node
  :color-matrix-node
  :reapeat-node
  :clip-node
  :rounded-clip-node
  :shadow-node
  :blend-node
  :cross-fade-node
  :text-node
  :blur-node
  :debug-node
  :gl-shader-node
  #+gtk-4-10
  :texture-scale-node
  #+gtk-4-10
  :mask-node
  #+gtk-4-14
  :fill-node
  #+gtk-4-14
  :stroke-node
  #+gtk-4-14
  :subsurface-node)  
Values:
:not-a-render-node
Error type. No node will ever have this type.
:container-node
A node containing a stack of children.
:cairo-node
A node drawing a `cairo_surface_t`
:color-node
A node drawing a single color rectangle.
:linear-gradient-node
A node drawing a linear gradient.
:repeating-linear-gradient-node
A node drawing a repeating linear gradient.
:radial-gradient-node
A node drawing a radial gradient.
:repeating-radial-gradient-node
A node drawing a repeating radial gradient.
:conic-gradient-node
A node drawing a conic gradient.
:border-node
A node stroking a border around an area.
:texture-node
A node drawing a `GdkTexture`.
:inset-shadow-node
A node drawing an inset shadow.
:outset-shadow-node
A node drawing an outset shadow.
:transform-node
A node that renders its child after applying a matrix transform.
:opacity-node
A node that changes the opacity of its child.
:color-matrix-node
A node that applies a color matrix to every pixel.
:repeat-node
A node that repeats the child's contents.
:clip-node
A node that clips its child to a rectangular area.
:rounded-clip-node
A node that clips its child to a rounded rectangle.
:shadow-node
A node that draws a shadow below its child.
:blend-node
A node that blends two children together.
:cross-fade-node
A node that cross-fades between two children.
:text-node
A node containing a glyph string.
:blur-node
A node that applies a blur.
:debug-node
Debug information that does not affect the rendering.
:gl-shader-node
A node that uses OpenGL fragment shaders to render.
:texture-scale-node
A node drawing a gdk:texture object scaled and filtered. Since 4.10
:mask-node
A node that masks one child with another. Since 4.10
:fill-node
A node that fills a path. Since 4.14
:stroke-node
A node that strokes a path. Since 4.14
:subsurface-node
A node that possibly redirects part of the scene graph to a subsurface. Since 4.14
Details:
The type of a node determines what the node is rendering.
See also:
2024-5-25
GEnum gsk:scaling-filter
Declaration:
(gobject:define-genum "GskScalingFilter" scaling-filter
  (:export t
   :type-initializer "gsk_scaling_filter_get_type")
  (:linear 0)
  (:nearest 1)
  (:trilinear 2))  
Values:
:linear
Linear interpolation filter.
:nearest
Nearest neighbor interpolation filter.
:trilinear
Linear interpolation along each axis, plus mipmap generation, with linear interpolation along the mipmap levels.
Details:
The filters used when scaling texture data. The actual implementation of each filter is deferred to the rendering pipeline.
See also:
2023-9-22
GEnum gsk:blend-mode
Declaration:
(gobject:define-genum "GskBlendMode" blend-mode
  (:export t
   :type-initializer "gsk_blend_mode_get_type")
  (:default 0)
  (:multiply 1)
  (:screen 2)
  (:overlay 3)
  (:darken 4)
  (:ligthen 5)
  (:color-dodge 6)
  (:color-burn 7)
  (:hard-light 8)
  (:soft-ligth 9)
  (:difference 10)
  (:exclusion 11)
  (:color 12)
  (:hue 13)
  (:saturation 14)
  (:luminosity 15))  
Values:
:default
The default blend mode, which specifies no blending.
:multiply
The source color is multiplied by the destination and replaces the destination.
:screen
Multiplies the complements of the destination and source color values, then complements the result.
:overlay
Multiplies or screens the colors, depending on the destination color value. This is the inverse of hard-list.
:darken
Selects the darker of the destination and source colors.
:ligthen
Selects the lighter of the destination and source colors.
:color-dodge
Brightens the destination color to reflect the source color.
:color-burn]{Darkens the destination color to reflect the source color.
:hard-ligth
Multiplies or screens the colors, depending on the source color value.
:soft-ligth
Darkens or lightens the colors, depending on the source color value.
:difference
Subtracts the darker of the two constituent colors from the lighter color.
:exclusion
Produces an effect similar to that of the difference mode but lower in contrast.
:color
Creates a color with the hue and saturation of the source color and the luminosity of the destination color.
:hue
Creates a color with the hue of the source color and the saturation and luminosity of the destination color.
:saturation
Creates a color with the saturation of the source color and the hue and luminosity of the destination color.
:luminosity
Creates a color with the luminosity of the source color and the hue and saturation of the destination color.
Details:
The blend modes available for render nodes. The implementation of each blend mode is deferred to the rendering pipeline. See Composting and Blending for more information on blending and blend modes.
See also:
2023-10-26
GEnum gsk:mask-mode
Declaration:
(gobject:define-genum "GskMaskMode" mask-mode
  (:export t
   :type-initializer "gsk_mask_mode_get_type")
  (:alpha 0)
  (:inverted-alpha 1)
  (:luminance 2)
  (:inverted-luminace 3))  
Values:
:alpha
Use the alpha channel of the mask.
inverted-alpha
Use the inverted alpha channel of the mask.
:luminance
Use the luminance of the mask, multiplied by mask alpha.
:inverted-luminance
Use the inverted luminance of the mask, multiplied by mask alpha.
Details:
The mask modes available for mask nodes. Since 4.10
See also:
2023-10-26
GskRenderNode gsk:render-node
Superclasses:
common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The gsk:render-node instance is the basic block in a scene graph to be rendered using the gsk:renderer object. Each node has a parent, except the top-level node. Each node may have child nodes.

Each node has an associated drawing surface, which has the size of the rectangle set when creating it.

Render nodes are meant to be transient. Once they have been associated to a gsk:renderer object it is safe to release any reference you have on them. All gsk:render-node instances are immutable, you can only specify their properties during construction.
See also:
2023-10-25
Function gsk:render-node-ref (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with an additional reference
Details:
Acquires a reference on the given render node.
See also:
2023-10-25
Function gsk:render-node-unref (node)
Arguments:
node -- a gsk:render-node instance
Details:
Releases a reference on the given render node. If the reference was the last, the resources associated to the node are freed.
See also:
2023-10-25
Function gsk:render-node-node-type (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node-type value with the type of node.
Details:
Returns the type of the render node.
See also:
2023-10-26
Function gsk:render-node-draw (node cr)
Arguments:
node -- a gsk:render-node instance
cr -- a cairo:context-t instance to draw to
Details:
Draw the contents of node to the given Cairo context. Typically, you will use this function to implement fallback rendering of render nodes on an intermediate Cairo context, instead of using the drawing context associated to the rendering buffer of a gdk:surface object.

For advanced nodes that cannot be supported using Cairo, in particular for nodes doing 3D operations, this function may fail.
See also:
2023-10-26
Function gsk:render-node-serialize (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The g:bytes instance representing the node.
Details:
Serializes the node for later deserialization via the gsk:render-node-deserialize function. No guarantees are made about the format used other than that the same version of GTK will be able to deserialize the result of a call to the gsk:render-node-serialize and gsk:render-node-deserialize functions will correctly reject files it cannot open that were created with previous versions of GTK.

The intended use of this functions is testing, benchmarking and debugging. The format is not meant as a permanent storage format.
See also:
2023-10-26
Function gsk:render-node-deserialize (bytes)
Arguments:
bytes -- a g:bytes instance containing the data
Returns:
The new gsk:render-node instance, or nil on error.
Details:
Loads data previously created via the gsk:render-node-serialize function. For a discussion of the supported format, see that function.
See also:
2023-10-26
Function gsk:render-node-write-to-file (node path)
Arguments:
node -- a gsk:render-node instance
path -- a pathname or namestring for the file to save it to
Returns:
True if saving was successful.
Details:
This function is mostly intended for use inside a debugger to quickly dump a render node to a file for later inspection.
Examples:
Example output for a gsk:color-node instance.
color {
  bounds: 0 0 10 20;
  color: rgb(255,0,0);
}    
See also:
2025-2-8
Function gsk:render-node-bounds (node bounds)
Arguments:
node -- a gsk:render-node instance
bounds -- a graphene:rect-t instance
Returns:
The bounds value with the boundaries.
Details:
Retrieves the boundaries of the render node. The render node will not draw outside of its boundaries.
See also:
2023-10-26
GskRenderNode gsk:container-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node that can contain other render nodes.
See also:
#2023-10-27
Function gsk:container-node-new (children)
Arguments:
children -- a list of gsk:render-node instances with the children of the render node
Returns:
The new gsk:container-node instance.
Details:
Creates a new container node for holding the given children. The new render node will acquire a reference to each of the children.
See also:
#2023-11-6
Function gsk:container-node-n-children (node)
Arguments:
node -- a gsk:container-node instance
Returns:
The unsigned integer with the number of children of node.
Details:
Retrieves the number of direct children of node.
See also:
#2023-11-6
Function gsk:container-node-child (node index)
Arguments:
node -- a gsk:container-node instance
index -- an unsigned integer with the position of the child to get
Returns:
The index'th child of node.
Details:
Gets one of the children of the container node.
See also:
#2023-11-6
GskRenderNode gsk:cairo-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a Cairo surface.
See also:
2023-10-27
Function gsk:cairo-node-new (bounds)
Arguments:
bounds -- a graphene:rect-t instance with the rectangle to render to
Returns:
The new gsk:render-node instance.
Details:
Creates a render node that will render a Cairo surface into the area given by bounds. You can draw to the Cairo surface using the gsk:cairo-node-draw-context function.
See also:
#2023-10-27
Function gsk:cairo-node-draw-context (node)
Arguments:
node -- a gsk:cairo-node instance for a Cairo surface
Returns:
The Cairo context used for drawing, use the cairo:destroy function when done drawing.
Details:
Creates a Cairo context for drawing using the surface associated to the render node. If no surface exists yet, a surface will be created optimized for rendering.
See also:
#2023-10-27
Function gsk:cairo-node-surface (node)
Arguments:
node -- a gsk:cairo-node instance for a Cairo surface
Returns:
The cairo:surface-t instance with a Cairo surface.
Details:
Retrieves the Cairo surface used by the render node.
See also:
#2023-10-27
GskRenderNode gsk:color-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a solid color.
See also:
#2023-10-25
Function gsk:color-node-new (rgba bounds)
Arguments:
rgba -- a gdk:rgba instance specifying a color
bounds -- a graphene:rect-t instance with the rectangle to render the color into
Returns:
The new gsk:color-node instance.
Details:
Creates a render node that will render the color specified by rgba into the area given by bounds.
See also:
#2023-10-25
Function gsk:color-node-color (node)
Arguments:
node -- a gsk:color-node instance
Returns:
The gdk:rgba instance with the color of the render node
Details:
Retrieves the color of the given render node.
See also:
#2023-10-25
GskRenderNode gsk:linear-gradient-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a linear gradient.
See also:
#2023-10-27
Function gsk:linear-gradient-node-new (bounds start end color-stops)
Arguments:
bounds -- a graphene:rect-t instance with the rectangle to render the linear gradient into
start -- a graphene:point-t instance with the point at which the linear gradient will begin
end -- a graphene:point-t instance with the point at which the linear gradient will finish
color-stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
Returns:
The new gsk:linear-gradient-node instance.
Details:
Creates a render node that will create a linear gradient from the given points and color stops, and render that into the area given by bounds.

The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1.
See also:
#2023-11-27
Function gsk:linear-gradient-node-start (node)
Arguments:
node -- a gsk:linear-gradient-node instance
Returns:
The graphene:point-t instance with the initial point.
Details:
Retrieves the initial point of the linear gradient.
See also:
#2023-11-27
Function gsk:linear-gradient-node-end (node)
Arguments:
node -- a gsk:linear-gradient-node instance
Returns:
The graphene:point-t instance with the final point.
Details:
Retrieves the final point of the linear gradient.
See also:
#2023-11-27
Function gsk:linear-gradient-node-n-color-stops (node)
Arguments:
node -- a gsk:linear-gradient-node instance
Returns:
The unsigned integer with the number of color stops.
Details:
Retrieves the number of color stops in the linear gradient.
See also:
#2023-11-27
Function gsk:linear-gradient-node-color-stops (node)
Arguments:
node -- a gsk:linear-gradient-node instance
Returns:
The list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors of the linear gradient.
Details:
Retrieves the color stops in the linear gradient.
See also:
#2023-11-27
GskRenderNode gsk:repeating-linear-gradient-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a repeating linear gradient.
See also:
#2023-10-27
Function gsk:repeating-linear-gradient-node-new (bounds start end color-stops)
Arguments:
bounds -- a graphene:rect-t instance with the rectangle to render the linear gradient into
start -- a graphene:point-t instance with the point at which the linear gradient will begin
end -- a graphene:point-t instance with the point at which the linear gradient will finish
color-stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
Returns:
The new gsk:linear-gradient-node instance.
Details:
Creates a render node that will create a repeating linear gradient from the given points and color stops, and render that into the area given by bounds.

The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1.
See also:
#2023-11-27
GskRenderNode gsk:radial-gradient-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a radial gradient.
See also:
#2023-10-27
Function gsk:radial-gradient-node-new (bounds center hradius vradius start end color-stops)
Arguments:
bounds -- a graphene:rect-t instance with the rectangle to render the linear gradient into
center -- a graphene:point-t instance with the center of the radial gradient
hradius -- a number coerced to float with the horizontal radius
vradius -- a number coerced to a float with the vertical radius
start -- a number coerced to a float with the percentage >= 0 that defines the start of the radial gradient around center
end -- a number coerced to a float with the percentage >= 0 that defines the end of the radial gradient around center
color-stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
Returns:
The new gsk:radial-gradient-node instance.
Details:
Creates a render node that will create a radial gradient. The radial gradient starts around center. The size of the gradient is dictated by hradius in horizontal orientation and by vradius in vertial orientation.

The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1.
See also:
#2023-11-27
Function gsk:radial-gradient-node-n-color-stops (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The unsigned integer with the number of color stops.
Details:
Retrieves the number of color stops in the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-color-stops (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors of the radial gradient.
Details:
Retrieves the color stops in the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-start (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The float with the start value for the radial gradient.
Details:
Retrieves the start value for the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-end (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The float with the end value for the radial gradient.
Details:
Retrieves the end value for the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-hradius (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The float with the horizontal radius for the radial gradient.
Details:
Retrieves the horizontal radius for the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-vradius (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The float with the vertical radius for the radial gradient.
Details:
Retrieves the vertical radius for the radial gradient.
See also:
#2023-11-27
Function gsk:radial-gradient-node-center (node)
Arguments:
node -- a gsk:radial-gradient-node instance
Returns:
The graphene:point-t instance with the center point for the radial gradient.
Details:
Retrieves the center point for the radial gradient.
See also:
#2023-11-27
GskRenderNode gsk:repeating-radial-gradient-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a repeating radial gradient.
See also:
#2023-10-27
Function gsk:repeating-radial-gradient-node-new (bounds center hradius vradius start end color-stops)
Arguments:
bounds -- a graphene:rect-t instance with the rectangle to render the linear gradient into
center -- a graphene:point-t instance with the center of the radial gradient
hradius -- a number coerced to a float with the horizontal radius
vradius -- a number coerced to a float with the vertical radius
start -- a number coerced to a float with the percentage >= 0 that defines the start of the radial gradient around center
end -- a number coerced to a float with the percentage >= 0 that defines the end of the radial gradient around center
color-stops -- a list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors defining the gradient
Returns:
Details:
Creates a render node that will create a repeating radial gradient. The repeating radial gradient starts around center. The size of the gradient is dictated by hradius in horizontal orientation and by vradius in vertial orientation.

The offsets of all color stops must be increasing. The first stop's offset must be >= 0 and the last stop's offset must be <= 1.
See also:
#2023-11-27
GskRenderNode gsk:conic-gradient-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a conic gradient.
See also:
#2023-10-27
Function gsk:conic-gradient-node-new (bounds center rotation color-stops)
Arguments:
bounds -- a graphene:rect-t instance with the bounds of the render node
center -- a graphene:point-t instance with the center of the gradient
rotation -- a float with the rotation of the gradient in degrees
stops -- a list with the color stops defining the gradient, the offset of all color steps must be increasing, the first stop's offset must be >= 0 and the last stop's offset must be <= 1
n-stops -- an integer with the number of elements in stops
Returns:
The new gsk:conic-gradient-node instance.
Details:
Creates a render node that draws a conic gradient. The conic gradient starts around center in the direction of rotation. A rotation of 0 means that the gradient points up. Color stops are then added clockwise.
See also:
#2023-11-24
Function gsk:conic-gradient-node-n-color-stops (node)
Arguments:
node -- a gsk:conic-gradient-node instance for a conic gradient
Returns:
The unsigned integer with the number of color stops.
Details:
Retrieves the number of color stops in the conic gradient.
See also:
#2023-11-23
Function gsk:conic-gradient-node-color-stops (node)
Arguments:
node -- a gsk:conic-gradient-node instance
Returns:
The list of the form '((offset1 color1) (offset2 color2) ...) with the offsets and colors of the conic gradient.
Details:
Retrieves the color stops in the conic gradient.
See also:
#2023-11-27
Function gsk:conic-gradient-node-center (node)
Arguments:
node -- a gsk:conic-gradient-node instance for a conic gradient
Returns:
The graphene:point-t instance with the center point for the gradient.
Details:
Retrieves the center pointer for the gradient.
See also:
#2023-11-23
Function gsk:conic-gradient-node-rotation (node)
Arguments:
node -- a gsk:conic-gradient-node instance
Returns:
The float with the rotation for the conic gradient.
Details:
Retrieves the rotation for the conic gradient in degrees.
See also:
#2023-11-23
GskRenderNode gsk:border-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a border.
See also:
2023-10-26
Function gsk:border-node-new (outline widths colors)
Arguments:
outline -- a gsk:rounded-rect instance describing the outline of the border
widths -- a list with 4 single floats for the stroke width of the border on the top, right, bottom, and left side respectively
colors -- a list with 4 gdk:rgba instances for the color used on the top, right, bottom, and left side
Returns:
The gsk:border-node instance.
Details:
Creates a border render node that will stroke a border rectangle inside the given outline. The 4 sides of the border can have different widths and colors.
See also:
2023-11-19
Function gsk:border-node-outline (node)
Arguments:
node -- a gsk:border-node instance
Returns:
The gsk:rounded-rect instance with the outline of the border
Details:
Retrieves the outline of the border.
See also:
2023-11-19
Function gsk:border-node-widths (node)
Arguments:
node -- a gsk:border-node instance for a border
Returns:
The list with 4 single floats for the top, right, bottom, and left stroke width of the border, respectively.
Details:
Retrieves the stroke widths of the border.
See also:
2023-11-19
Function gsk:border-node-colors (node)
Arguments:
node -- a gsk:border-node instance for a border
Returns:
The list with 4 gdk:rgba instances for the top, right, bottom, and left color of the border.
Details:
Retrieves the colors of the border.
See also:
#2023-10-27
GskRenderNode gsk:texture-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a gdk:texture object.
See also:
#2023-10-27
Function gsk:texture-node-new (texture bounds)
Arguments:
texture -- a gdk:texture object
bounds -- a graphene:rect-t instance with the rectangle to render the texture into
Returns:
The new gsk:texure-node instance.
Details:
Creates a render node that will render the given texture into the area given by bounds.
See also:
#2023-11-23
Function gsk:texture-node-texture (node)
Arguments:
node -- a gsk:texture-node instance
Returns:
The gdk:texture object.
Details:
Retrieves the texture used when creating this render node.
See also:
#2023-11-23
GskRenderNode gsk:inset-shadow-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for an inset shadow.
See also:
#2023-10-27
Function gsk:inset-shadow-node-new (outline color dx dy spread radius)
Arguments:
outline -- a gsk:rounded-rect instance with the outline of the region containing the shadow
color -- a gdk:rgba instance with the color of the shadow
dx -- a number coerced to a float with the horizontal offset of the shadow
dy -- a number coerced to a float with the vertical offset of the shadow
spread -- a number coerced to a float how far the shadow spreads towards the inside
radius -- a number coerced to a float how much blur to apply to the shadow
Returns:
The gsk:inset-shadow-node instance.
Details:
Creates a render node that will render an inset shadow into the box given by outline.
See also:
#2023-11-27
Function gsk:inset-shadow-node-outline (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The gsk:rounded-rect instance with the rounded rectangle.
Details:
Retrieves the outline rectangle of the inset shadow.
See also:
#2023-11-27
Function gsk:inset-shadow-node-color (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The gdk:rgba instance with the color of the shadow.
Details:
Retrieves the color of the inset shadow.
See also:
#2023-11-27
Function gsk:inset-shadow-node-dx (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The float with an offset, in pixels.
Details:
Retrieves the horizontal offset of the inset shadow.
See also:
#2023-11-27
Function gsk:inset-shadow-node-dy (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The float with an offset, in pixels.
Details:
Retrieves the vertical offset of the inset shadow.
See also:
#2023-11-27
Function gsk:inset-shadow-node-spread (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The float with the size of the shadow, in pixels.
Details:
Retrieves how much the shadow spreads inwards.
See also:
#2023-11-27
Function gsk:inset-shadow-node-blur-radius (node)
Arguments:
node -- a gsk:inset-shadow-node instance
Returns:
The float with the blur radius, in pixels.
Details:
Retrieves the blur radius to apply to the shadow.
See also:
#2023-11-27
GskRenderNode gsk:outset-shadow-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for an outset shadow.
See also:
#2023-10-27
Function gsk:outset-shadow-node-new (outline color dx dy spread radius)
Arguments:
outline -- a gsk:rounded-rect instance with the outline of the region containing the shadow
color -- a gdk:rgba instance with the color of the shadow
dx -- a number coerced to a float with the horizontal offset of the shadow
dy -- a number coerced to a float with the vertical offset of the shadow
spread -- a number coerced to a float how far the shadow spreads towards the inside
radius -- a number coerced to a float how much blur to apply to the shadow
Returns:
Details:
Creates a render node that will render an outset shadow into the box given by outline.
See also:
#2023-11-27
Function gsk:outset-shadow-node-outline (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The gsk:rounded-rect instance with the rounded rectangle.
Details:
Retrieves the outline rectangle of the outset shadow.
See also:
#2023-11-27
Function gsk:outset-shadow-node-color (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The gdk:rgba instance with the color of the shadow.
Details:
Retrieves the color of the outset shadow.
See also:
#2023-11-27
Function gsk:outset-shadow-node-dx (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The float with an offset, in pixels.
Details:
Retrieves the horizontal offset of the outset shadow.
See also:
#2023-11-27
Function gsk:outset-shadow-node-dy (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The float with an offset, in pixels.
Details:
Retrieves the vertical offset of the outset shadow.
See also:
#2023-11-27
Function gsk:outset-shadow-node-spread (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The float with the size of the shadow, in pixels.
Details:
Retrieves how much the shadow spreads inwards.
See also:
#2023-11-27
Function gsk:outset-shadow-node-blur-radius (node)
Arguments:
node -- a gsk:outset-shadow-node instance
Returns:
The float with the blur radius, in pixels.
Details:
Retrieves the blur radius to apply to the shadow.
See also:
#2023-11-27
GskRenderNode gsk:transform-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node applying a gsk:transform instance to its single child render node.
See also:
#2023-10-27
Function gsk:transform-node-new (child transform)
Arguments:
child -- a gsk:render-node instance with the render node to transform
transform -- a gsk:transform instance with the transform to apply
Returns:
The new gsk:transform-node instance.
Details:
Creates a render node that will transform the given child with the given transform.
See also:
#2023-10-27
Function gsk:transform-node-child (node)
Arguments:
node -- a gsk:transform-node instance
Returns:
The gsk:render-node instance with the child render node that is getting transformed.
Details:
Gets the child render node that is getting transformed by the given node.
See also:
#2023-10-27
Function gsk:transform-node-transform (node)
Arguments:
node -- a gsk:transform-node instance
Returns:
The gsk:transform instance.
Details:
Retrieves the gsk:transform instance used by node.
See also:
#2023-10-27
GskRenderNode gsk:opacity-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node controlling the opacity of its single child render node.
See also:
#2023-10-27
Function gsk:opacity-node-new (child opacity)
Arguments:
child -- a gsk:render-node instance
opacity -- a number coerced to a float with the opacity to apply
Returns:
The new gsk:opacity-node instance.
Details:
Creates a render node that will draw the child with reduced opacity.
See also:
#2023-11-27
Function gsk:opacity-node-child (node)
Arguments:
child -- a gsk:render-node instance
Returns:
The gsk:render-node instance with the child that is getting opacityed.
Details:
Gets the child node that is getting opacityed by the given node.
See also:
#2023-11-27
Function gsk:opacity-node-opacity (node)
Arguments:
child -- a gsk:render-node instance
Returns:
The float with the opacity factor.
Details:
Gets the transparency factor for an opacity node.
See also:
#2023-11-27
GskRenderNode gsk:color-matrix-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node controlling the color matrix of its single child render node.
See also:
2023-10-27
Function gsk:color-matrix-node-new (child matrix offset)
Arguments:
child -- a gsk:render-node instance with the child render node to draw
matrix -- a graphene:matrix-t instance with the matrix to apply
offset -- a graphene:vec4-t instance with the values to add to the color
Returns:
The new gsk:rende-node instance.
Details:
Creates a render node that will draw the child render node with reduced matrix.
See also:
#2023-10-27
Function gsk:color-matrix-node-child (node)
Arguments:
node -- a gsk:color-matrix-node instance
Returns:
The gsk:render-node instance with the child render node that is getting its colors modified.
Details:
Gets the child render node that is getting its colors modified by the given node.
See also:
#2023-10-27
Function gsk:color-matrix-node-color-matrix (node)
Arguments:
node -- a gsk:color-matrix-node instance
Returns:
The graphene:matrix-t instance with a 4x4 color matrix.
Details:
Retrieves the color matrix used by node.
See also:
gsk:colr-matrix-node
graphene:matrix-t
#2023-10-27
Function gsk:color-matrix-node-color-offset (node)
Arguments:
node -- a gsk:color-matrix-node instance
Returns:
The graphene:vec4-t instance with a color vector
Details:
Retrieves the color offset used by node.
See also:
#2023-10-27
GskRenderNode gsk:repeat-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node repeating its single child render node.
See also:
#2023-10-27
Function gsk:repeat-node-new (bounds child child-bounds)
Arguments:
bounds -- a graphene:rect-t instance with the bounds of the area to be painted
child -- a gsk:render-node instance with the child to repeat
child-bounds -- a graphene:rect-t instance with the area of the child to repeat or nil to use the child's bounds
Returns:
The new gsk:repeat-node instance.
Details:
Creates a render node that will repeat the drawing of child across the given bounds.
See also:
#2023-11-27
Function gsk:repeat-node-child (node)
Arguments:
node -- a gsk:repeat-node instance
Returns:
The gsk:render-node instance with the child.
Details:
Retrieves the child of node.
See also:
#2023-11-27
Function gsk:repeat-node-child-bounds (node)
Arguments:
node -- a gsk:repeat-node instance
Returns:
The graphene:rect-t instance with the bounding rectangle.
Details:
Retrieves the bounding rectangle of the child of node.
See also:
#2023-11-27
GskRenderNode gsk:clip-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node applying a rectangular clip to its single child render node.
See also:
2023-10-27
Function gsk:clip-node-new (child clip)
Arguments:
child -- a gsk:render-node instance with the render node to draw
clip -- a graphene:rect-t instance with the clip to apply
Returns:
The new gsk:render-node instance.
Details:
Creates a render node that will clip the child render node to the area given by clip.
See also:
#2023-10-27
Function gsk:clip-node-child (node)
Arguments:
node -- a gsk:clip-node instance
Returns:
The gsk:render-node instance with the child render node that is getting clipped.
Details:
Gets the child render node that is getting clipped by the given node.
See also:
#2023-10-27
Function gsk:clip-node-clip (node)
Arguments:
node -- a gsk:clip-node instance
Returns:
The graphene:rect-t instance with a clip rectangle.
Details:
Retrieves the clip rectangle for node.
See also:
#2023-10-27
GskRenderNode gsk:rounded-clip-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node applying a rounded rectangle clip to its single child render node.
See also:
#2023-10-27
Function gsk:rounded-clip-node-new (child clip)
Arguments:
child -- a gsk:render-node instance with the node to draw
clip -- a gsk:rounded-rect instance with the clip to apply
Returns:
The new gsk:rounded-clip-node instance.
Details:
Creates a render node that will clip the child node to the area given by clip.
See also:
#2023-11-29
Function gsk:rounded-clip-node-child (node)
Arguments:
node -- a gsk:rounded-clip-node instance
Returns:
The gsk:render-node instance with the child that is getting clipped.
Details:
Gets the child node that is getting clipped by the given node.
See also:
#2023-11-29
Function gsk:rounded-clip-node-clip (node)
Arguments:
node -- a gsk:rounded-clip-node instance
Returns:
The gsk:rounded-rect instance with the rounded rectangle.
Details:
Retrievs the rounded rectangle used to clip the contents of node.
See also:
#2023-11-29
GskRenderNode gsk:shadow-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node drawing one or more shadows behind its single child render node.
See also:
#2023-10-27
Function gsk:shadow-node-new (child shadows)
Arguments:
child -- a gsk:render-node instance for the node to draw
shadows -- a list of the form '((color1 dx1 dy1 radius1) (color2 dx2 dy2 radius2) ...) with the shadows to apply
Returns:
The new gsk:shadow-node instance.
Details:
Creates a render node that will draw a child with the given shadows below it.
See also:
2025-2-12
Function gsk:shadow-node-shadow (node index)
Arguments:
node -- a gsk:shadow-node instance
index -- an unsigned integer with the given index
Returns:
The list of the form '(color dxi dy radius) with the shadow data.
Details:
Retrieves the shadow data at the given index.
See also:
#2023-11-29
Function gsk:shadow-node-n-shadows (node)
Arguments:
node -- a gsk:shadow-node instace
Returns:
The unsigned integer with the number of shadows.
Details:
Retrieves the number of shadows in node.
See also:
#2023-11-29
Function gsk:shadow-node-child (node)
Arguments:
node -- a gsk:shadow-node instance
Returns:
The gsk:render-node instance with the child render node.
Details:
Retrieves the child render node of the shadow node.
See also:
#2023-11-29
GskRenderNode gsk:blend-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node applying a blending function between its two child nodes.
See also:
2023-10-25
Function gsk:blend-node-new (bottom top mode)
Arguments:
bottom -- a gsk:render-node instance with the bottom node to be drawn
top -- a gsk:render-node instance with the top node to be blended onto the bottom node
mode -- a gsk:blend-mode value with the blend mode to use
Returns:
The new gsk:blend-node instance.
Details:
Creates a render node that will use mode to blend the top node onto the bottom node.
See also:
#2023-10-26
Function gsk:blend-node-bottom-child (node)
Arguments:
node -- a gsk:blend-node instance
Returns:
The gsk:render-node instance with the bottom child node
Details:
Retrieves the bottom render node child of node.
See also:
#2023-10-26
Function gsk:blend-node-top-child (node)
Arguments:
node -- a gsk:blend-node instance
Returns:
The gsk:render-node instance with the top child node
Details:
Retrieves the top render node child of node.
See also:
#2023-10-26
Function gsk:blend-node-blend-mode (node)
Arguments:
node -- a gsk:blend-node instance
Returns:
The gsk:blend-mode value with the blend mode.
Details:
Retrieves the blend mode used by node.
See also:
#2023-10-26
GskRenderNode gsk:cross-fade-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node cross fading between two child render nodes.
See also:
#2023-10-27
Function gsk:cross-fade-node-new (start end progress)
Arguments:
start -- a gsk:render-node instance with the start render node to be drawn
end -- a gsk:render-node instance with the render node to be cross-fadeed onto the start node
progress -- a float how far the fade has progressed from start to end, the value will be clamped to the range [0 ... 1]
Returns:
The new gsk:cross-fade-node instance.
Details:
Creates a render node that will do a cross-fade between start and end.
See also:
#2023-11-6
Function gsk:cross-fade-node-start-child (node)
Arguments:
node -- a gsk:cross-fade-node instance
Returns:
The gsk:render-node instance.
Details:
Retrieves the child render node at the beginning of the cross-fade.
See also:
#2023-11-6
Function gsk:cross-fade-node-end-child (node)
Arguments:
node -- a gsk:cross-fade-node instance
Returns:
The gsk:render-node instance.
Details:
Retrieves the child render node at the end of the cross-fade.
See also:
#2023-11-6
Function gsk:cross-fade-node-progress (node)
Arguments:
node -- a gsk:cross-fade-node instance
Returns:
The float with the progress value, between 0 and 1.
Details:
Retrieves the progress value of the cross fade node.
See also:
#2023-11-6
GskRenderNode gsk:text-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node drawing a set of glyphs.
See also:
#2023-10-27
Function gsk:text-node-new (font glyphs color offset)
Arguments:
font -- a pango:font object containing the glyphs
glyphs -- a pango:glyph-string instance to render
color -- a gdk:rgba instance with the foreground color to render with
offset -- a graphene:point-t instance with the offset of the baseline
Returns:
The new gsk:text-node instance.
Details:
Creates a render node that renders the given glyphs. Note that color may not be used if the font contains color glyphs.
See also:
#2023-11-29
Function gsk:text-node-font (node)
Arguments:
node -- a gsk:text-node instance
Returns:
The pango:font object with the font
Details:
Returns the font used by the text node.
See also:
#2023-11-29
Function gsk:text-node-color (node)
Arguments:
node -- a gsk:text-node instance
Returns:
The gdk:rgba instance with the text color
Details:
Retrieves the color used by the text node.
See also:
#2023-11-29
Function gsk:text-node-has-color-glyphs (node)
Arguments:
node -- a gsk:text-node instance
Returns:
True if the text node has color glyphs.
Details:
Checks whether the text node has color glyphs.
See also:
#2023-11-23
Function gsk:text-node-num-glyphs (node)
Arguments:
node -- a gsk:text-node instance
Returns:
The unsigned integer with the number of glyphs.
Details:
Retrieves the number of glyphs in the text node.
See also:
#2023-11-29
Function gsk:text-node-offset (node)
Arguments:
node -- a gsk:text-node instance
Returns:
The graphene:point-t instance with the horizontal and vertical offsets.
Details:
Retrieves the offset applied to the text node.
See also:
gsk:text-node
grapene:point-t
#2023-11-29
GskRenderNode gsk:blur-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node applying a blur effect between its single child node.
See also:
2023-10-26
Function gsk:blur-node-new (child radius)
Arguments:
child -- a gsk:render-node instance with the child to blur
radius -- a float with the blur radius
Returns:
The new gsk:blur-node instance.
Details:
Creates a render node that blurs the child render node.
See also:
#2023-10-26
Function gsk:blur-node-child (node)
Arguments:
node -- a gsk:blur-node instance
Returns:
The gsk:render-node instance with the blurred child render node.
Details:
Retrieves the child render node of the blur render node.
See also:
#2023-10-26
Function gsk:blur-node-radius (node)
Arguments:
node -- a gsk:blur-node instance
Returns:
The float with the blur radius.
Details:
Retrieves the blur radius of the blur render node.
See also:
#2023-10-26
GskRenderNode gsk:debug-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node that emits a debugging message when drawing its child render node.
See also:
#2023-10-27
Function gsk:debug-node-new (child message)
Arguments:
child -- a gsk:render-node instance with the child to add debug info for
message -- a string with the debug message
Returns:
The new gsk:debug-node instance.
Details:
Creates a render node that will add debug information about the given child. Adding this node has no visual effect.
See also:
#2023-11-16
Function gsk:debug-node-child (node)
Arguments:
node -- a debug gsk:debug-node instance
Returns:
The child gsk:render-node instance.
Details:
Gets the child node that is getting drawn by the given node.
See also:
#2023-11-16
Function gsk:debug-node-message (node)
Arguments:
node -- a gsk:debug-node instance
Returns:
The string with the debug message.
Details:
Gets the debug message that was set on this render node.
See also:
#2023-11-16
GskRenderNode gsk:texture-scale-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
A render node for a gdk:texture object.

Since 4.10
See also:
#2024-11-15
Function gsk:texture-scale-node-filter (node)
Arguments:
node -- a gsk:texture-scale-node instance
Returns:
Details:
Retrieves the gsk:scaling-filter value used when creating the render node.

Since 4.10
See also:
#2024-11-16
Function gsk:texture-scale-node-texture (node)
Arguments:
node -- a gsk:texture-scale-node instance
Returns:
The gdk:texture object.
Details:
Retrieves the texture used when creating the render node.

Since 4.10
See also:
#2024-11-16
GskRenderNode gsk:mask-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A render node masking one child node with another.

Since 4.10
See also:
#2024-11-15
Function gsk:mask-node-new (source mask mode)
Arguments:
source -- a gsk:render-node instance with the source node to be drawn
mask -- a gsk:render-node instance with the node to be used as mask
mode -- a gsk:mask-mode value with the mask mode to use
Details:
Creates a gsk:render-node instance that will mask a given node by another. The mode value determines how the mask values are derived from the colors of the mask. Applying the mask consists of multiplying the mask value with the alpha of the source.

Since 4.10
See also:
#2024-12-2
Function gsk:mask-node-mask (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with the mask child node
Details:
Retrieves the gsk:render-node instance with the mask child of the node.

Since 4.10
See also:
#2024-12-2
Function gsk:mask-node-mask-mode (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:mask-mode value with the mask mode.
Details:
Retrieves the mask mode used by node.

Since 4.10
See also:
#2024-12-2
Function gsk:mask-node-source (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with the source child of the node.
Details:
Retrieves the gsk:render-node instance with the source child of the node.

Since 4.10
See also:
#2024-12-2
GskRenderNode gsk:fill-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A render node filling the area given by a gsk:path instance and a gsk:fill-rule value with the child node.

Since 4.14
See also:
#2024-11-15
Function gsk:fill-node-new (child path rule)
Arguments:
child -- a gsk:render-node instance with the node to fill the area with
path -- a gsk:path instance with the path describing the area to fill
rule -- a gsk:fill-rule value with the fill rule to use
Details:
Creates a gsk:render-node instance that will fill the child in the area given by path and rule.

Since 4.14
See also:
#2024-12-2
Function gsk:fill-node-child (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with child that is getting drawn
Details:
Gets the child node that is getting drawn by the given node.

Since 4.14
See also:
#2024-12-2
Function gsk:fill-node-fill-rule (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:fill-rule value.
Details:
Retrieves the fill rule used to determine how the path is filled.

Since 4.14
See also:
#2024-12-2
Function gsk:fill-node-path (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:path instance.
Details:
Retrieves the path used to describe the area filled with the contents of the node.

Since 4.14
See also:
#2024-12-2
GskRenderNode gsk:stroke-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A render node that will fill the area determined by stroking the the given gsk:path instance using the gsk:stroke attributes.

Since 4.14
See also:
#2024-11-15
Function gsk:stroke-node-new (child path stroke)
Arguments:
child -- a gsk:render-node instance with the node to stroke the area with
path -- a gsk:path instance with the path describing the area to stroke
stroke -- a gsk:stroke value with the stroke attributes to use
Details:
Creates a gsk:render-node instance that will fill the outline generated by stroking the given path using the attributes defined in stroke. The area is filled with child.

Since 4.14
See also:
#2024-12-2
Function gsk:stroke-node-child (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with the child that is getting drawn.
Details:
Gets the child node that is getting drawn by the given node.

Since 4.14
See also:
#2024-12-2
Function gsk:stroke-node-path (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:path instance.
Details:
Retrieves the path that will be stroked with the contents of node.

Since 4.14
See also:
#2024-12-2
Function gsk:stroke-node-stroke (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:stroke value.
Details:
Retrieves the stroke attributes used in node.

Since 4.14
See also:
#2024-12-2
GskRenderNode gsk:subsurface-node
Superclasses:
gsk:render-node, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
A render node that potentially diverts a part of the scene graph to a subsurface.

Since 4.14
See also:
#2024-11-15
Function gsk:subsurface-node-new (child subsurface)
Arguments:
child -- a gsk:render-node instance
subsurface -- a pointer with the subsurface to use
Returns:
The new gsk:render-node instance.
Details:
Creates a gsk:render-node instance that will possibly divert the child node to a subsurface.
Notes:
Since subsurfaces are currently private, these nodes cannot currently be created outside of GTK. See the gtk:graphics-offload documentation.
This constructor is not directly available to language bindings.

Since 4.14
See also:
#2024-12-2
Function gsk:subsurface-node-subsurface (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The pointer with the subsurface.
Details:
Gets the subsurface that was set on this node. This function is not directly available to language bindings.

Since 4.14
See also:
#2024-12-2
Function gsk:subsurface-node-child (node)
Arguments:
node -- a gsk:render-node instance
Returns:
The gsk:render-node instance with the child.
Details:
Gets the child node that is getting drawn by the given node.

Since 4.14
See also:
#2024-12-2

GskRoundedRect

GEnum gsk:corner
Declaration:
(gobject:define-genum "GskCorner" corner
  (:export t
   :type-initializer "gsk_corner_get_type")
  (:top-left 0)
  (:top-right 1)
  (:bottom-right 2)
  (:bottom-left 3))  
Values:
:top-left
The top left corner.
:top-right
The top right corner.
:bottom-right
The bottom right corner.
:bottom-left
The bottom left corner.
Details:
The corner indices used by the gsk:rounded-rect instance.
See also:
2023-10-27
CStruct gsk:rounded-rect
Slot Access Functions:
Details:
A rectangular region with rounded corners. Application code should normalize rounded rectangles using the gsk:rounded-rect-normalize function. This function will ensure that the bounds of the rounded rectangle are normalized and ensure that the corner values are positive and the corners do not overlap.

All functions taking a gsk:rounded-rect instance as an argument will internally operate on a normalized copy. All functions returning a gsk:rounded-rect instance will always return a normalized one.

The algorithm used for normalizing corner sizes is described in the CSS specification.
(cffi:defcstruct rounded-rect
  (bounds (:struct graphene:rect-t))
  (corner (:struct graphene:size-t) :count 4))  
bounds
A graphene:rect-t instance with the bounds of the rounded rectangle.
corner
An array of graphene:size-t instances with the size of the 4 rounded corners.
See also:
2023-10-27
Function gsk:rounded-rect-bounds (rect)
Syntax:
(gsk:rounded-rect-bounds rect) => bounds
Arguments:
rect -- a gsk:rounded-rect instance
bounds -- a graphene:rect-t instance
Details:
Accessor of the bounds slot of the rounded rectangle.
See also:
2023-12-4
Function gsk:rounded-rect-corner (rect nth)
Syntax:
(gsk:rounded-rect-corner rect nth) => corner
Arguments:
rect -- a gsk:rounded-rect instance
nth -- an integer with the number of the corner to retrieve
corner -- a graphene:size-t instance with the size of the nth corner
Details:
Accessor of the nth corner of the rounded rectangle.
See also:
2023-12-4
Function gsk:rounded-rect-init (rect bounds top-left top-right bottom-right bottom-left)
Arguments:
rect -- a gsk:rounded-rect instance to initialize
bounds -- a graphene:rect-t instance describing the bounds
top-left -- a graphene:size-t instance with the rounding radius of the top left corner
top-right -- a graphene:size-t instance with the rounding radius of the top right corner
bottom-right -- a graphene:size-t instance with the rounding radius of the bottom right corner
bottom-left -- a graphene:size-t instance with the rounding radius of the bottom left corner
Returns:
The initialized gsk:rounded-rect instance.
Details:
Initializes the given rect with the given values. This function will implicitly normalize the rounded rectangle before returning.
See also:
2023-12-4
Function gsk:rounded-rect-init-copy (rect src)
Arguments:
rect -- a gsk:rounded-rect instance
src -- a gsk:rounded-rect instance
Returns:
The initialized gsk:rounden-rect instance.
Details:
Initializes rect using the given src rounded rectangle. This function will not normalize the rounded rectangle, so make sure the source rounded rectangle is normalized.
See also:
2023-12-4
Function gsk:rounded-rect-init-from-rect (rect bounds radius)
Arguments:
rect -- a gsk:rounded-rect instance
bounds -- a graphene:rect-t instance
radius -- a number coerced to a float with the border radius
Returns:
The initialized gsk:rounded-rect instance.
Details:
Initializes rect to the given bounds and sets the radius of all four corners to radius.
See also:
2023-12-4
Function gsk:rounded-rect-normalize (rect)
Arguments:
rect -- a gsk:rounded-rect instance
Returns:
The normalized gsk:rounded-rect instance.
Details:
Normalizes the passed rounded rectangle. This function will ensure that the bounds of the rounded rectangle are normalized and ensure that the corner values are positive and the corners do not overlap.
See also:
#2023-10-28
Function gsk:rounded-rect-offset (rect dx dy)
Arguments:
rect -- a gsk:rounded-rect instance
Returns:
The offst gsk:rounded-rect instance.
Details:
Offsets the origin of the bound by dx and dy. The size and corners of the rounded rectangle are unchanged.
See also:
#2023-10-28
Function gsk:rounded-rect-shrink (rect top right bottom left)
Arguments:
rect -- a gsk:rounded-rect instance
top -- a number coerced to a float how far to move the top side downwards
right -- a number coerced to a float how far to move the right side to the left
bottom -- a number coerced to a float how far to move the bottom side upwards
left -- a number coerced to a float how far to move the left side to the right
Returns:
The resized gsk:rounded-rect instance.
Details:
Shrinks (or grows) the given rounded rectangle by moving the 4 sides according to the offsets given. The corner radii will be changed in a way that tries to keep the center of the corner circle intact. This emulates CSS behavior.

This function also works for growing rounded rectangles if you pass negative values for the arguments.
See also:
#2023-10-28
Function gsk:rounded-rect-is-rectilinear (rect)
Arguments:
rect -- a gsk:rounded-rect instance to check
Returns:
True if the rounded rectangle is rectilinear.
Details:
Checks if all corners of rect are right angles and the rounded rectangle covers all of its bounds. This information can be used to decide if the gsk:clip-node-new or the gsk:rounded-clip-node-new function should be called.
See also:
#2023-10-28
Function gsk:rounded-rect-contains-point (rect point)
Arguments:
rect -- a gsk:rounded-rect instance
point -- a graphene:point-t instance with the point to check
Returns:
True if the point is inside the rounded rectangle.
Details:
Checks if the given point is inside the rounded rectangle. This function returns false if the point is in the rounded corner areas.
See also:
#2023-10-28
Function gsk:rounded-rect-contains-rect (rect other)
Arguments:
rect -- a gsk:rounded-rect instance
other -- a graphene:rect-t instance with the rectangle to check
Returns:
True if other is fully contained inside the rounded rectangle.
Details:
Checks if the given other is contained inside the rounded rectangle. This function returns false if other extends into one of the rounded corner areas.
See also:
#2023-10-28
Function gsk:rounded-rect-intersects-rect (rect other)
Arguments:
rect -- a gsk:rounded-rect instance
other -- a graphene:rect-t instance to check
Returns:
True if other intersects with the rounded rectangle.
Details:
Checks if part of the given other is contained inside the rounded rectangle. This function returns false if other only extends into one of the rounded corner areas but not into the rounded rectangle itself.
See also:
#2023-10-28

GskTransform

GEnum gsk:transform-category
Declaration:
(gobject:define-genum "GskTransformCategory" transform-category
  (:export t
   :type-initializer "gsk_transform_category_get_type")
   :unknown
   :any
   :3d
   :2d
   :2d-affine
   :2d-translate
   :identity)  
Values:
:unknown
The category of the matrix has not been determined.
:any
Analyzing the matrix concluded that it does not fit in any other category.
:3d
The matrix is a 3D matrix. This means that the w column (the last column) has the values (0, 0, 0, 1).
:2d
The matrix is a 2D matrix. This is equivalent to the graphene:matrix-is-2d function returning true. In particular, this means that Cairo can deal with the matrix.
:2d-affine
The matrix is a combination of 2D scale and 2D translation operations. In particular, this means that any rectangle can be transformed exactly using this matrix.
:2d-translate
The matrix is a 2D translation.
:identity
The matrix is the identity matrix.
Details:
The categories of matrices relevant for GSK and GTK. Note that the enumeration values are ordered in a way that any category includes matrices of all later categories. So if you want to for example check if a matrix is a 2D matrix, the category value of the matrix is greater or equal the :2d value.

Also keep in mind that rounding errors may cause matrices to not conform to their categories. Otherwise, matrix operations done via multiplication will not worsen categories. So for the matrix multiplication C = A * B the result has the category category(C) = (MIN (category(A), category(B)).
Examples:
With the helper function
(defun category-value (category)
  (cffi:convert-to-foreign category 'gsk:transform-category))    
you can check if a matrix with category is a 2D matrix with
(>= (category-value category) (category-value :2d))    
See also:
2024-4-21
GBoxed gsk:transform
Declaration:
(glib:define-gboxed-opaque transform ¸"GskTransform"
  :export t
  :type-initializer "gsk_transform_get_type"
  :alloc (%transform-new))  
Returned by:
Details:
The gsk:transform structure is a structure to describe transform matrices. Unlike the graphene:matrix-t structure, the gsk:transform structure retains the steps in how a transform was constructed, and allows inspecting them. It is modeled after the way CSS describes transforms.

The gsk:transform instances are immutable and cannot be changed after creation. This means code can safely expose them as properties of objects without having to worry about others changing them.
See also:
2024-4-21
Function gsk:transform-new ()
Returns:
The new gsk:transform instance.
Details:
Creates a new transform matrix.
See also:
2024-4-21
Function gsk:transform-category (transform)
Arguments:
transform -- a gsk:transform instance
Returns:
The gsk:transform-category value with the category of the transform matrix.
Details:
Returns the category this transform matrix belongs to.
See also:
2024-4-21
Function gsk:transform-parse (str)
Arguments:
str -- a string to parse
Returns:
The gsk:transform instance with the transform matrix.
Details:
Parses the given string into a transform matrix. Strings printed via the gsk:transform-to-string function can be read in again successfully using this function. If the str argument does not describe a valid transform matrix, false is returned.
Examples:
(gsk:transform-parse "translate(1,2)")
=> #<GSK:TRANSFORM {100A325D83}>
(gsk:transform-to-translate *)
=> (1.0 2.0)
(gsk:transform-parse "translate(1,2) scale(3)")
=> #<GSK:TRANSFORM {100A327283}>
(gsk:transform-to-2d *)
=> (3.0 0.0 0.0 3.0 1.0 2.0)
(gsk:transform-parse "xxxx") => NIL    
See also:
2024-4-21
Function gsk:transform-to-string (transform)
Arguments:
transform -- a gsk:transform instance
Returns:
The string for transform.
Details:
Converts a tansform matrix into a string that is suitable for printing and can later be parsed with the gsk:transform-parse function.
Examples:
(gsk:transform-to-string (gsk:transform-new)) => "none"
(graphene:with-point (p 1/2 2)
  (let ((transform (gsk:transform-translate (gsk:transform-new) p)))
    (gsk:transform-to-string transform)))
=> "translate(0.5, 2)"
(gsk:transform-to-string (gsk:transform-parse "translate(1,2)"))
=> "translate(1, 2)"    
See also:
2024-4-21
Function gsk:transform-to-matrix (transform matrix)
Arguments:
transform -- a gsk:transform instance
matrix -- a graphene:matrix-t instance with the matrix to set
Returns:
The graphene:matrix-t instance with the matrix.
Details:
Computes the actual values of the transform matrix and stores it in matrix. The previous values of matrix will be ignored.
See also:
2024-4-21
Function gsk:transform-to-2d (transform)
Arguments:
transform -- a gtk:transform instance
Returns:
The (xx xy yx yy dx dy) list with the single floats of the 2D transformation matrix.
Details:
Converts a gsk:transform instace to a 2D transformation matrix. The transform argument must be a 2D transformation. If you are not sure, use the gsk:transform-category function to check.

The returned values have the following layout:
| xx yx |   |  a  b  0 |
| xy yy | = |  c  d  0 |
| dx dy |   | tx ty  1 |  
This function can be used to convert between a gsk:transform instance and a matrix from other 2D drawing libraries, in particular Cairo.
See also:
2024-3-21
Function gsk:transform-to-2d-components (transform)
Arguments:
transform -- a gsk:transform instance
Returns:
The (xskew yskew xscale yscale angle dx dy) list with single floats for the 2D transformation factors.
Details:
Converts a gsk:transform instance to 2D transformation factors. The transform argument must be a 2D transformation. If you are not sure, use the gsk:transform-category function to check.

Since 4.6
Examples:
Recreate an equivalent transform matrix from the factors returned by this function.
(graphene:with-point (p)
  (gsk:transform-skew
      (gsk:transform-scale
          (gsk:transform-rotate
              (gsk:transform-translate (gsk:transform-new)
                                       (graphene:point-init p dx dy))
              angle)
          xscale yscale)
      xskew yskew))    
See also:
2024-4-21
Function gsk:transform-to-affine (transform)
Arguments:
transform -- a gsk:transform instance
Returns:
The (xscale yscale dx dy) list of single floats with the 2D affine transformation factors.
Details:
Converts a gsk:transform instance to 2D affine transformation factors. The transform argument must be a 2D transformation. If you are not sure, use the gsk:transform-category function to check.
See also:
2024-4-21
Function gsk:transform-to-translate (transform)
Arguments:
transform -- a gsk:transform instance
Returns:
The (dx dy) list with single floats for a translation operation.
Details:
Converts a gsk:transform instance to a translation operation. The transform arugment must be a 2D transformation. If you are not sure, use the gsk:transform-category function to check.
See also:
2024-4-21
Function gsk:transform-transform (transform other)
Arguments:
transform -- a gsk:transform instance
other -- a gsk:transform instance
Returns:
The new gsk:transform instance.
Details:
Applies all the operations from other to transform.
See also:
2024-4-21
Function gsk:transform-invert (transform)
Arguments:
transform -- a gsk:transform instance to invert
Returns:
The gsk:transform instance with the inverted transform or nil if the transform cannot be inverted.
Details:
Inverts the given transform. If transform is not invertible, nil is returned. Note that inverting nil also returns nil, which is the correct inverse of nil. If you need to differentiate between those cases, you should check transform is not nil before calling this function.
See also:
2024-4-21
Function gsk:transform-matrix (transform matrix)
Arguments:
transform -- a gsk:transform instance
matrix -- a graphene:matrix-t instance
Returns:
The new gsk:transform instance.
Details:
Multiplies transform with the given matrix.
See also:
2024-4-21
Function gsk:transform-translate (transform point)
Arguments:
transform -- a gsk:transform instance
point -- a graphene:point-t instance with the point to translate the transform matrix by
Returns:
The new gsk:transform instance.
Details:
Translates the transform matrix in 2dimensional space by point.
See also:
2024-4-21
Function gsk:transform-translate-3d (transform point)
Arguments:
transform -- a gsk:transform instance
point -- a graphene:point3d-t instance with the point to translate the transform matrix by
Returns:
The new gsk:transform instance.
Details:
Translates the transform matrix by point.
See also:
2024-4-21
Function gsk:transform-rotate (transform angle)
Arguments:
transform -- a gsk:transform instance
angle -- a number coerced to a single float with the rotation angle, in degrees (clockwise)
Returns:
The new gsk:transform instance.
Details:
Rotates the transformation matrix angle degrees in 2D, or in 3D speak, around the z axis.
See also:
2024-4-21
Function gsk:transform-rotate-3d (transform angle axis)
Arguments:
transform -- a gsk:transform instance
angle -- a number coerced to a single float with the rotation angle, in degrees and clockwise
axis -- a graphene:vec3-t instance with the rotation axis
Returns:
The new gsk:transform instance.
Details:
Rotates the transform matrix angle degrees around axis. For a rotation in 2D space, use the gsk:transform-rotate function.
See also:
2024-4-21
Function gsk:transform-scale (transform xfactor yfactor)
Arguments:
transform -- a gsk:transform instance
xfactor -- a number coerced to a single float with the scaling factor on the x axis
yfactor -- a number coerced to a single float with the scaling factor on the y axis
Returns:
The new gsk:transform instance.
Details:
Scales transform in 2-dimensional space by the given factors. Use the gsk:transform-scale-3d function to scale in all 3 dimensions.
See also:
2024-4-21
Function gsk:transform-scale-3d (transform xfactor yfactor zfactor)
Arguments:
transform -- a gsk:transform instance
xfactor -- a number coerced to a single float with the scaling factor on the x axis
yfactor -- a number coerced to a single float with the scaling factor on the y axis
zfactor -- a number coerced to a single float with the scaling factor on the z axis
Returns:
A new gsk:transform instance.
Details:
Scales the transform matrix by the given factors.
See also:
2024-4-21
Function gsk:transform-skew (transform xskew yskew)
Arguments:
transform -- a gsk:transform instance
xskew -- a number coerced to a single float with the skew factor on the x axis, in degrees
yskew -- a number coerced to a single float with the skew factor on the y axis, in degrees
Returns:
The new gsk:transform instance.
Details:
Applies a skew transform.

Since 4.6
See also:
2024-4-21
Function gsk:transform-perspective (transform depth)
Arguments:
transform -- a gsk:transform instance
depth -- a number coerced to a single float with the distance of the z=0 plane, lower values give a more flattened pyramid and therefore a more pronounced perspective effect
Returns:
The new gsk:transform instance.
Details:
Applies a perspective projection transform. This transform scales points in x and y based on their z value, scaling points with positive z values away from the origin, and those with negative z values towards the origin. Points on the z=0 plane are unchanged.
See also:
2024-4-21
Function gsk:transform-equal (first second)
Arguments:
first -- a first gsk:transform instance
second -- a second gsk:transform instance
Returns:
True if the two transforms perform the same operation.
Details:
Checks two transforms for equality.
See also:
2024-4-21
Function gsk:transform-transform-bounds (transform rect bounds)
Arguments:
transform -- a gsk:transform instance
rect -- a graphene:rect-t instance
bounds -- a graphene:rect-t instance for the bounds of the transformed rectangle
Returns:
The graphene:rect-t instance with the bounds.
Details:
Transforms a graphene:rect-t instance using the given transform matrix. The result is the bounding box containing the coplanar quad.
See also:
2024-4-21
Function gsk:transform-transform-point (transform point result)
Arguments:
transform -- a gsk:transform instance
point -- a graphene:point-t instance
result -- a graphene:point-t instance for the transformed point
Returns:
The graphene:point-t instance with the transformed point.
Details:
Transforms a graphene:point-t instance using the given transform matrix.
See also:
2024-4-21

GskGLShader

Other Functions in gsk

Function gsk:texture-scale-new (texture bounds filter)
Arguments:
texture -- a gdk:texture object to scale
bounds -- a graphene:rect-t instance with the size of the texture to scale to
filter -- a gsk:scaling-filter value how to scale the texture
Returns:
The new gsk:texture-scale-node instance.
Details:
Creates a node that scales the texture to the size given by the bounds using the filter and then places it at the bounds’ position. Note that further scaling and other transformations which are applied to the node will apply linear filtering to the resulting texture, as usual.

This node is intended for tight control over scaling applied to a texture, such as in image editors and requires the application to be aware of the whole render tree as further transforms may be applied that conflict with the desired effect of this node.

Since 4.10
See also:
#2024-11-16

Package gdk-pixbuf

GDK-Pixbuf is a library for image loading and manipulation. The GDK-Pixbuf documentation contains both the programmer's guide and the API reference. This is the API documentation of a Lisp binding to the GDK-Pixbuf library.

Library version numbers

These macros and variables let you check the version of GDK-Pixbuf you are linking against.
Constant gdk-pixbuf:+version+
Details:
Contains the full version of the GDK-Pixbuf library as a string. This is the version currently in use by a running program.
See also:
2024-4-2
Constant gdk-pixbuf:+major-version+
Details:
The major version number of the GDK-Pixbuf library. E.g. in GDK-Pixbuf version 2.42.8 this is 2. This variable is in the library, so represents the GDK-Pixbuf library you have loaded.
See also:
2024-4-2
Constant gdk-pixbuf:+minor-version+
Details:
The minor version number of the GDK-Pixbuf library. E.g. in GDK-Pixbuf version 2.42.8 this is 42. This variable is in the library, so represents the GDK-Pixbuf library you have loaded.
See also:
2024-4-2
Constant gdk-pixbuf:+micro-version+
Details:
The micro version number of the GDK-Pixbuf library. E.g. in GDK-Pixbuf version 2.42.8 this is 8. This variable is in the library, so represents the GDK-Pixbuf library you have loaded.
See also:
2024-4-2

The GdkPixbuf object

GEnum gdk-pixbuf:colorspace
Declaration:
(gobject:define-genum "GdkColorspace" colorspace
  (:export t
   :type-initializer "gdk_colorspace_get_type")
  :rgb)  
Values:
:rgb
Indicates a red/green/blue additive color space.
Details:
This enumeration defines the color spaces that are supported by the GDK-Pixbuf library. Currently only RGB is supported.
See also:
2024-6-29
Class gdk-pixbuf:pixbuf
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
bits-per-sample
The bits-per-sample property of type :int (Read / Write / Construct Only)
The number of bits per sample. Currently only 8 bit per sample are supported.
Allowed values: [1,16]
Default value: 8
colorspace
The colorspace property of type gdk-pixbuf:colorspace (Read / Write / Construct Only)
The colorspace in which the samples are interpreted.
Default value: :rgb
has-alpha
The has-alpha property of type :boolean (Read / Write / Construct Only)
Whether the pixbuf has an alpha channel.
Default value: false
height
The height property of type :int (Read / Write / Construct Only)
The number of rows of the pixbuf.
Allowed values: >= 1
Default value: 1
n-channels
The n-channels property of type :int (Read / Write / Construct Only)
The number of samples per pixel. Currently, only 3 or 4 samples per pixel are supported.
Allowed values: >= 0
Default value: 3
pixel-bytes
The pixel-bytes property of type g:bytes (Read / Write / Construct Only)
Readonly pixel data.
pixels
The pixels property of type :pointer (Read / Write / Construct Only)
The pointer to the pixel data of the pixbuf.
rowstride
The rowstride property of type :int (Read / Write / Construct Only)
The number of bytes between the start of a row and the start of the next row. This number must be at least as large as the width of the pixbuf.
Allowed values: >= 1
Default value: 1
width
The width property of type :int (Read / Write / Construct Only)
The number of columns of the pixbuf.
Allowed values: >= 1
Default value: 1
Slot Access Functions:
Details:
The gdk-pixbuf:pixbuf object contains information that describes an image in memory. 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).
Image Data:
Image data in a pixbuf is stored in memory in uncompressed, packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right. There may be padding at the end of a row. The "rowstride" value of a pixbuf, as returned by the gdk-pixbuf:pixbuf-rowstride function, indicates the number of bytes between rows.
Examples:
The following code illustrates a simple put-pixel function for RGB pixbufs with 8 bits per channel with an alpha channel. It is not included in the gdk-pixbuf:pixbuf library for performance reasons. Rather than making several function calls for each pixel, your own code can take shortcuts.
(defun put-pixel (pixbuf x y red green blue alpha)
  (let ((n-channels (gdk-pixbuf:pixbuf-n-channels pixbuf))
        (rowstride (gdk-pixbuf:pixbuf-rowstride pixbuf))
        (pixels (gdk-pixbuf:pixbuf-pixels pixbuf)))
    ;; Add offset to the pointer pixels into the pixbuf
    (cffi:incf-pointer pixels (+ (* y rowstride) (* x n-channels)))
    ;; Set the color of the point and the alpha value
    (setf (cffi:mem-aref pixels :uchar 0) red)
    (setf (cffi:mem-aref pixels :uchar 1) green)
    (setf (cffi:mem-aref pixels :uchar 2) blue)
    (setf (cffi:mem-aref pixels :uchar 3) alpha)))    
This function will not work for pixbufs with images that are other than 8 bits per sample or channel, but it will work for most of the pixbufs that GTK uses.
Notes:
If you are doing memcpy() of raw pixbuf data, note that the last row in the pixbuf may not be as wide as the full rowstride, but rather just as wide as the pixel data needs to be. That is, it is unsafe to do memcpy (dest, pixels, rowstride * height) to copy a whole pixbuf. Use the gdk-pixbuf:pixbuf-copy function instead, or compute the width in bytes of the last row as width * ((n_channels * bits_per_sample + 7) / 8).
2024-6-29
Accessor gdk-pixbuf:pixbuf-bits-per-sample (object)
Syntax:
(gdk-pixbuf:pixbuf-bits-per-sample object) => bits-per-sample
Arguments:
object -- a gdk-pixbuf:pixbuf object
bits-per-sample -- an integer with the number of bits per sample
Details:
Accessor of the bits-per-sample slot of the gdk-pixbuf:pixbuf class. Queries the number of bits per color sample in a pixbuf. Currently only 8 bit per sample are supported.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-colorspace (object)
Syntax:
(gdk-pixbuf:pixbuf-colorspace object) => colorspace
Arguments:
object -- a gdk-pixbuf:pixbuf object
colorspace -- a gdk-pixbuf:colorspace value
Details:
Accessor of the colorspace slot of the gdk-pixbuf:pixbuf class. Querries the colorspace in which the samples are interpreted.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-has-alpha (object)
Syntax:
(gdk-pixbuf:pixbuf-has-alpha object) => has-alpha
Arguments:
object -- a gdk-pixbuf:pixbuf object
has-alpha -- a boolean whether the pixbuf has an alpha channel
Details:
Accessor of the has-alpha slot of the gdk-pixbuf:pixbuf class. Queries whether a pixbuf has an alpha channel (opacity information).
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-height (object)
Syntax:
(gdk-pixbuf:pixbuf-height object) => height
Arguments:
object -- a gdk-pixbuf:pixbuf object
height -- an integer with the number of rows of the pixbuf
Details:
Accessor of the height slot of the gdk-pixbuf:pixbuf class. Queries the height of a pixbuf.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-n-channels (object)
Syntax:
(gdk-pixbuf:pixbuf-n-channels object) => n-channels
Arguments:
object -- a gdk-pixbuf:pixbuf object
n-channels -- an integer with the number of channels
Details:
Accessor of the n-channels slot of the gdk-pixbuf:pixbuf class. Queries the number of channels of a pixbuf.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-pixel-bytes (object)
Syntax:
(gdk-pixbuf:pixbuf-pixel-bytes object) => pixel-bytes
Arguments:
object -- a gdk-pixbuf:pixbuf object
pixel-bytes -- a g:bytes instance with the pixel data
Details:
Accessor of the pixel-bytes slot of the gdk-pixbuf:pixbuf class. Querries the readonly pixel data.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-pixels (object)
Syntax:
(gdk-pixbuf:pixbuf-pixels object) => pixels
Arguments:
object -- a gdk-pixbuf:pixbuf object
pixels -- a pointer to the pixel data of pixbuf
Details:
Accessor of the pixels slot of the gdk-pixbuf:pixbuf class. Queries a pointer to the pixel data of a pixbuf. Please see the section called "Image Data" in the gdk-pixbuf:pixbuf documentation 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.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-rowstride (object)
Syntax:
(gdk-pixbuf:pixbuf-rowstride object) => rowstride
Arguments:
object -- a gdk-pixbuf:pixbuf object
rowstride -- an integer with the distance between row starts
Details:
Accessor of the rowstride slot of the gdk-pixbuf:pixbuf class. 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.
See also:
2024-6-29
Accessor gdk-pixbuf:pixbuf-width (object)
Syntax:
(gdk-pixbuf:pixbuf-width object) => width
Arguments:
object -- a gdk-pixbuf:pixbuf object
width -- an integer with the width of the pixbuf
Details:
Accessor of the width slot of the gdk-pixbuf:pixbuf class. Queries the width of a pixbuf.
See also:
2024-6-29
Function gdk-pixbuf:pixbuf-pixels-with-length (pixbuf length)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
length -- an unsigned integer with the length of the binary data
Returns:
The pointer to the pixel data of the pixbuf.
Details:
Queries a pointer to the pixel data of a pixbuf. Please see the section on image data in the gdk-pixbuf:pixbuf documentation 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.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-byte-length (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
Returns:
The integer with the length of the pixel data.
Details:
Returns the length of the pixel data, in bytes.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-option (pixbuf key)
Syntax:
(gdk-pixbuf:pixbuf-option pixbuf key) => value
(setf (gdk-pixbuf:pixbuf-option pixbuf key) value)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
key -- a string with a key
value -- a string with a value
Details:
The gdk-pixbuf:pixbuf-option function looks up key in the list of options that may have been attached to the pixbuf when it was loaded, or that may have been attached. The (setf gdk-pixbuf:pixbuf-option) function attaches a key/value pair as an option to a pixbuf. If key already exists in the list of options attached to pixbuf, the new value is ignored.

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.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-remove-option (pixbuf key)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf oject
key -- a string representing the key to remove
Returns:
True if an option was removed, false if not.
Details:
Remove the key/value pair option attached to a pixbuf.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-copy-options (src dest)
Arguments:
src -- a gdk-pixbuf:pixbuf to copy options from
dest -- a gdk-pixbuf:pixbuf to copy options to
Returns:
True on sucess.
Details:
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 have already applied, such as the "orientation" option after rotating the image.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-read-pixels (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
Returns:
The pointer to the pixel data.
Details:
Returns 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 the gdk-pixbuf:pixbuf-pixels function is called on a read-only pixbuf.
See also:
#2024-6-29

File Loading

Introduction to fileloading

The GDK-Pixbuf library provides a simple mechanism for loading an image from a file in synchronous fashion. This means that the library takes control of the application while the file is being loaded. From the user's point of view, the application will block until the image is done loading.

This interface can be used by applications in which blocking is acceptable while an image is being loaded. It can also be used to load small images in general. Applications that need progressive loading can use the gdk-pixbuf:pixbuf-loader API functionality instead.

Functions for file loading

Function gdk-pixbuf:pixbuf-new-from-file (path)
Arguments:
path -- a pathname or namestring with the file to load, in the GLib file name encoding
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil if any of several error conditions occurred: the file could not be opened, there was no loader for the format of the file, there was not enough memory to allocate the image buffer, or the image file contained invalid data.
Details:
Creates a new pixbuf by loading an image from a file. The file format is detected automatically.
See also:
2024-11-21
Function gdk-pixbuf:pixbuf-new-from-file-at-size (path width height)
Arguments:
path -- a pathname or namestring with the file to load, in the GLib file name encoding
width -- an integer with the width the image should have or -1 to not constrain the width
height -- an integer with the height the image should have or -1 to not constrain the height
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil if any of several error conditions occurred: the file could not be opened, there was no loader for the format of the file, there was not enough memory to allocate the image buffer, or the image file contained invalid data.
Details:
Creates a new pixbuf by loading an image from a file. The file format is detected automatically.

The image will be scaled to fit in the requested size, preserving the aspect ratio of the image. Note that the returned pixbuf may be smaller than width x height, if the aspect ratio requires it. To load an image at the requested size, regardless of the aspect ratio, use the gdk-pixbuf:pixbuf-new-from-file-at-scale function.
See also:
2024-11-21
Function gdk-pixbuf:pixbuf-new-from-file-at-scale (path width height preserve)
Arguments:
path -- a pathname or namestring with the file to load, in the GLib file name encoding
width -- an integer with the width the image should have or -1 to not constrain the width
height -- an integer with the height the image should have or -1 to not constrain the height
preserve -- true to preserve the aspect ratio of the image
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil if any of several error conditions occurred: the file could not be opened, there was no loader for the format of the file, there was not enough memory to allocate the image buffer, or the image file contained invalid data.
Details:
Creates a new pixbuf by loading an image from a file. The file format is detected automatically. The image will be scaled to fit in the requested size, optionally preserving the aspect ratio of the image.

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 the aspect ratio, a width or height of -1 means to not scale the image at all in that dimension.
See also:
2024-11-21
Function gdk-pixbuf:pixbuf-new-from-resource (path)
Arguments:
path -- a string with the path of the resource file
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil 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.
Details:
Creates a new pixbuf by loading an image from a resource. The file format is detected automatically.
See also:
2024-11-21
Function gdk-pixbuf:pixbuf-new-from-resource-at-scale (path width height preserve)
Arguments:
path -- a string with the path of the resource file
width -- an integer with the width the image should have or -1 to not constrain the width
height -- an integer with the height the image should have or -1 to not constrain the height
preserve -- true to preserve the aspect ratio of the image
Returns:
The newly created gdk-pixbuf:pixbuf object, or nil 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.
Details:
Creates a new pixbuf by loading an image from an resource. The file format is detected automatically.

The image will be scaled to fit in the requested size, optionally preserving the aspect ratio of the image. 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 the aspect ratio, a width or height of -1 means to not scale the image at all in that dimension.
See also:
2024-11-21
Function gdk-pixbuf:pixbuf-file-info (path)
Arguments:
path -- a pathname or namestring with the name of the file to identify
Returns:
format -- a gdk-pixbuf:pixbuf-format instance describing the image format of the file or nil if the image format was not recognized
width -- an integer with the width of the image, or nil
height -- an integer with the height of the image, or nil
Details:
Parses an image file far enough to determine its format and size.
See also:
2024-5-30
Function gdk-pixbuf:pixbuf-file-info-async (path cancellable func)
Arguments:
path -- a pathname or namestring with the file to identify
cancellable -- a g:cancellable object, or nil to ignore
func -- a g:async-ready-callback callback function to call when the pixbuf is loaded
Details:
Asynchronously parses an image file far enough to determine its format and size. For more details see the gdk-pixbuf:pixbuf-file-info function, which is the synchronous version of this function.

When the operation is finished, the func callback function will be called in the main thread. You can then call the gdk-pixbuf:pixbuf-file-info-finish function to get the result of the operation.
See also:
2024-5-30
Function gdk-pixbuf:pixbuf-file-info-finish (result)
Arguments:
result -- a g:async-result instance
Returns:
format -- a gdk-pixbuf:pixbuf-format instance describing the image format of the file or nil if the image format was no recognized
width -- an integer with the width of the image
height -- an integer with the height of the image
Details:
Finishes an asynchronous pixbuf parsing operation started with the gdk-pixbuf:pixbuf-file-info-async function.
See also:
2024-11-21

File Saving

Introduction to file saving

These functions allow to save a gdk-pixbuf:pixbuf object in a number of file formats. The formatted data can be written to a file or to a memory buffer. The gdk-pixbuf:pixbuf library can also call a user-defined callback on the data, which allows to write the image to a socket or store it in a database.

Functions for file saving

Function gdk-pixbuf:pixbuf-save (pixbuf filename type)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
filename -- a string with the name of file to save
type -- a string with the name of file format
Returns:
The boolean whether an error was set.
Details:
Saves pixbuf to a file in format type. By default, "jpeg", "png", "ico" and "bmp" are possible file formats to save in, but more formats may be installed. The list of all writable formats can be determined in the following way:
void add_if_writable (GdkPixbufFormat *data, GSList **list)
{
  if (gdk_pixbuf_format_is_writable (data))
    *list = g_slist_prepend (*list, data);
}

GSList *formats = gdk_pixbuf_get_formats (); GSList *writable_formats = NULL; g_slist_foreach (formats, add_if_writable, &writable_formats); g_slist_free (formats);
If error is set, nil will be returned. Possible errors include those in the GDK_PIXBUF_ERROR domain and those in the G_FILE_ERROR domain.

The variable argument list should be NULL-terminated; if not empty, it should contain pairs of strings that modify the save parameters. For example:
gdk_pixbuf_save (pixbuf, handle, "jpeg", &error,
                "quality", "100", NULL);  
Currently only few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. JPEG and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch.

Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. The PNG compression level can be specified using the "compression" parameter; it's value is in an integer in the range of [0,9].

ICC color profiles can also be embedded into PNG and TIFF images. The "icc-profile" value should be the complete ICC profile encoded into base64.
gchar *contents;
gchar *contents_encode;
gsize length;
g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm",
                     &contents, &length, NULL);
contents_encode = g_base64_encode ((const guchar *) contents, length);
gdk_pixbuf_save (pixbuf, handle, "png", &error,
                 "icc-profile", contents_encode,
                 NULL);  
TIFF images recognize: (1) a "bits-per-sample" option (integer) which can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample; (2) a "compression" option (integer) which can be 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff documentation and tiff.h for all supported codec values); (3) an "icc-profile" option (zero-terminated string) containing a base64 encoded ICC color profile.

ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO.
See also:
#2024-6-29

Image Data in Memory

Introduction to image data in memory

The most basic way to create a pixbuf is to wrap an existing pixel buffer with a gdk-pixbuf:pixbuf object. You can use the gdk-pixbuf:pixbuf-new-from-data function to do this. You need to specify the destroy notification function that will be called when the data buffer needs to be freed. This will happen when a gdk-pixbuf:pixbuf object is finalized by the reference counting functions If you have a chunk of static data compiled into your application, you can pass in nil as the destroy notification function so that the data will not be freed.

The gdk-pixbuf:pixbuf-new function can be used as a convenience to create a pixbuf with an empty buffer. This is equivalent to allocating a data buffer using malloc() and then wrapping it with the gdk-pixbuf:pixbuf-new-from-data function. The gdk-pixbuf:pixbuf-new function will compute an optimal rowstride so that rendering can be performed with an efficient algorithm.

You can also copy an existing pixbuf with the gdk-pixbuf:pixbuf-copy function. The copy function will actually duplicate the pixel data in memory and create a new gdk-pixbuf:pixbuf instance for it.

Functions for image data in memory

Function gdk-pixbuf:pixbuf-new (colorspace has-alpha bits-per-sample width height)
Arguments:
colorspace -- a gdk-pixbuf:colorspace value for the image
has-alpha -- a boolean whether the image should have transparency information
bits-per-sample -- an integer with number of bits per color sample
width -- an integer with the width of image in pixels, must be > 0
height -- an integer with the height of image in pixels, must be > 0
Returns:
The newly created gdk-pixbuf:pixbuf object with a reference count of 1, or nil if not enough memory could be allocated for the image buffer.
Details:
Creates a new gdk-pixbuf:pixbuf object 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.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-new-from-bytes (data colorspace has-alpha bits-per-sample width height rowstride)
Arguments:
data -- a g:bytes instance with the image data in 8-bit sample packed format
colorspace -- a gdk-pixbuf:colorspace value for the image
has-alpha -- a boolean whether the image should have transparency information
bits-per-sample -- an integer with number of bits per color sample
width -- an integer with the width of image in pixels, must be > 0
height -- an integer with the height of image in pixels, must be > 0
rowstride -- an integer with the distance in bytes between row starts
Returns:
The newly created gdk-pixbuf:pixbuf object with a reference count of 1.
Details:
Creates a new gdk-pixbuf:pixbuf object out of in-memory readonly image data. Currently only RGB images with 8 bits per sample are supported.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-new-subpixbuf (pixbuf x y width height)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
x -- an integer with the x coord in pixbuf
y -- an integer with the y coord in pixbuf
width -- an integer with the width of region in pixbuf
height -- an integer with the height of region in pixbuf
Returns:
The new gdk-pixbuf:pixbuf object.
Details:
Creates a new pixbuf which represents a sub-region of pixbuf. The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to pixbuf, so pixbuf will not be finalized until the new pixbuf is finalized.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-copy (pixbuf)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
Returns:
The newly created pixbuf with a reference count of 1, or nil if not enough memory could be allocated.
Details:
Creates a new gdk-pixbuf:pixbuf object with a copy of the information in the specified pixbuf.
See also:
#2024-6-29

Scaling

Introduction to scaling

The gdk-pixbuf:pixbuf library contains functions to scale pixbufs, to scale pixbufs and composite against an existing image, and to scale pixbufs and composite against a solid color or checkerboard. Compositing a checkerboard is a common way to show an image with an alpha channel in image-viewing and editing software.

Since the full-featured gdk-pixbuf:pixbuf-scale, gdk-pixbuf:pixbuf-composite, and gdk-pixbuf:pixbuf-composite-color functions are rather complex to use and have many arguments, two simple convenience functions are provided, the gdk-pixbuf:pixbuf-scale-simple and gdk-pixbuf:pixbuf-composite-color-simple functions which create a new pixbuf of a given size, scale an original image to fit, and then return the new pixbuf.

If the destination pixbuf was created from a readonly source, these operations will force a copy into a mutable buffer.

Scaling and compositing functions take advantage of MMX hardware acceleration on systems where MMX is supported. If the gdk-pixbuf:pixbuf library is built with the Sun mediaLib library, these functions are instead accelerated using mediaLib, which provides hardware acceleration on Intel, AMD, and Sparc chipsets. If desired, mediaLib support can be turned off by setting the GDK_DISABLE_MEDIALIB environment variable.

The following example demonstrates handling an expose event by rendering the appropriate area of a source image, which is scaled to fit the widget, onto the window of the widget. The source image is rendered against a checkerboard, which provides a visual representation of the alpha channel if the image has one. If the image does not have an alpha channel, calling the gdk-pixbuf:pixbuf-composite-color function has exactly the same effect as calling the gdk-pixbuf:pixbuf-scale function.

Example: Handling an expose event.
gboolean
expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
{
  GdkPixbuf *dest;

dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);

gdk_pixbuf_composite_color (pixbuf, dest, 0, 0, event->area.width, event->area.height, -event->area.x, -event->area.y, (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf), (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf), GDK_INTERP_BILINEAR, 255, event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);

gdk_draw_pixbuf (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], dest, 0, 0, event->area.x, event->area.y, event->area.width, event->area.height, GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);

gdk_pixbuf_unref (dest);

return TRUE; }

Functions for scaling

GEnum gdk-pixbuf:pixbuf-interp-type
Declaration:
(gobject:define-genum "GdkInterpType" pixbuf-interp-type
  (:export t
   :type-initializer "gdk_interp_type_get_type")
  (:nearest 0)
  (:tiles 0)
  (:bilinear 0)
  (:hyper 0))  
Values:
:nearest
Nearest neighbor sampling: This is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be fine when scaling up.
:tiles
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.
:bilinear
Bilinear interpolation: Best quality/speed balance. Use this mode by default. 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.
:hyper
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 since 2.38, as in reality it has a lower quality than the :bilinear filter.
Details:
This enumeration describes the different interpolation modes that can be used with the scaling functions. The :nearest mode is the fastest scaling method, but has horrible quality when scaling down. The :bilinear mode is the best choice if you are not 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.
See also:
#2024-6-29
GEnum gdk-pixbuf:pixbuf-rotation
Declaration:
(gobject:define-genum "GdkPixbufRotation" pixbuf-rotation
  (:export t
   :type-initializer "gdk_pixbuf_rotation_get_type")
  (:none 0)
  (:counterclockwise 90)
  (:upsidedown 180)
  (:clockwise 270))  
Values:
:none
No rotation.
:counterclockwise
Rotate by 90 degrees.
:upsidedown
Rotate by 180 degrees.
:clockwise
Rotate by 270 degrees.
Details:
The possible rotations which can be passed to the gdk-pixbuf:pixbuf-rotate-simple function. To make them easier to use, their numerical values are the actual degrees.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-scale-simple (src width height interp)
Arguments:
src -- a gdk-pixbuf:pixbuf object
width -- an integer with the width of destination image
height -- an integer with the height of destination image
interp -- a gdk-pixbuf:pixbuf-interp-type interpolation type for the transformation
Returns:
The new gdk-pixbuf:pixbuf object, or nil if not enough memory could be allocated for it.
Details:
Create a new gdk-pixbuf:pixbuf object containing a copy of src scaled to width x height. Leaves src unaffected. The interp mode should be :nearest if you want maximum speed, but when scaling down the :nearest mode is usually unusably ugly. The default interp mode should be :bilinear which offers reasonable quality and speed.

You can scale a sub-portion of src by creating a sub-pixbuf pointing into src, see the gdk-pixbuf:pixbuf-new-subpixbuf function.

For more complicated scaling/compositing see the gdk-pixbuf:pixbuf-scale and gdk-pixbuf:pixbuf-composite functions.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-scale (src dest x y width height xoffset yoffset xscale  yscale interp)
Arguments:
src -- a gdk-pixbuf:pixbuf object
dest -- a gdk-pixbuf:pixbuf object into which to render the results
x -- an integer with the left coordinate for region to render
y -- an integer with the top coordinate for region to render
width -- an integer with the width of the region to render
height -- an integer with the height of the region to render
xoffset -- a number coerced to a double float with the offset in the x direction, currently rounded to an integer
yoffset -- a number coerce to a double float with the offset in the y direction, currently rounded to an integer
xscale -- a number coerced to a double float with the scale factor in the x direction
yscale -- a number coerced to a double float with the scale factor in the y direction
interp -- a gdk-pixbuf:pixbuf-interp-type interpolation type for the transformation
Details:
Creates a transformation of the source image src by scaling by xscale and yscale then translating by xoffset and yoffset, then renders the rectangle (x,y,width,height) of the resulting image onto the destination image replacing the previous contents.

Try to use the gdk-pixbuf:pixbuf-scale-simple function first, this function is the industrial-strength power tool you can fall back to if the gdk-pixbuf:pixbuf-scale-simple function is not 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.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-composite-color-simple (src width height interp alpha size color1 color2)
Arguments:
src -- a gdk-pixbuf:pixbuf object
width -- an integer with the width of destination image
height -- an integer with the height of destination image
interp -- a gdk-pixbuf:pixbuf-interp-type interpolation type for the transformation
alpha -- an integer with the overall alpha for source image (0..255)
size -- an integer with the size of checks in the checkboard, must be a power of two
color1 -- an unsigned integer with the color of check at upper left
color2 -- an unsigned integer with the color of the other check
Returns:
The new gdk-pixbuf:pixbuf object, or nil if not enough memory could be allocated for it.
Details:
Creates a new gdk-pixbuf:pixbuf object by scaling src to width x height and compositing the result with a checkboard of colors color1 and color2.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-composite (src dest x y width height xoffset yoffset xscale  yscale interp alpha)
Arguments:
src -- a gdk-pixbuf:pixbuf object
dest -- a gdk-pixbuf:pixbuf object into which to render the results
x -- an integer with the left coordinate for region to render
y -- an integer with the top coordinate for region to render
width -- an integer with the width of the region to render
height -- an integer with the height of the region to render
xoffset -- a number coerced to a double float with the offset in the x direction, currently rounded to an integer
yoffset -- a number coerced to a double float with the offset in the y direction, currently rounded to an integer
xscale -- a number coerced to a double float with the scale factor in the x direction
yscale -- a number coerced to a double float with the scale factor in the y direction
interp -- a gdk-pixbuf:pixbuf-interp-type interpolation type for the transformation
alpha -- an integer with the overall alpha for source image (0..255)
Details:
Creates a transformation of the source image src by scaling by xscale and yscale then translating by xoffset and yoffset. This gives an image in the coordinates of the destination pixbuf. The rectangle (x,y,width,height) is then composited 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.

Figure: Composite

See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-composite-color (src dest x y width height xoffset yoffset xscale  yscale interp alpha xcheck ycheck size color1 color2)
Arguments:
src -- a gdk-pixbuf:pixbuf object
dest -- a gdk-pixbuf:pixbuf object into which to render the results
x -- an integer with the left coordinate for region to render
y -- an integer with the top coordinate for region to render
width -- an integer with the width of the region to render
height -- an integer with the height of the region to render
xoffset -- a number coerced to a double float with the offset in the x direction, currently rounded to an integer
yoffset -- a number coerced to a double float with the offset in the y direction, currently rounded to an integer
xscale -- a number coerced to a double float with the scale factor in the x direction
yscale -- a number coerced to a double float with the scale factor in the y direction
interp -- a gdk-pixbuf:pixbuf-interp-type interpolation type for the transformation
alpha -- an integer with the overall alpha for source image (0..255)
xcheck -- an integer with the x offset for the checkboard, origin of checkboard is at (-xcheck, -ycheck)
ycheck -- an integer with the y offset for the checkboard
size -- an integer with the size of checks in the checkboard, must be a power of two
color1 -- an unsigned integer with the color of check at upper left
color2 -- an unsigned integer with the color of the other check
Details:
Creates a transformation of the source image src by scaling by xscale and yscale then translating by xoffset and yoffset, then composites the rectangle (x,y,width,height) of the resulting image with a checkboard of the colors color1 and color2 and renders it onto the destination image.

See the gdk-pixbuf:pixbuf-composite-color-simple function for a simpler variant of this function suitable for many tasks.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-rotate-simple (src angle)
Arguments:
src -- a gdk-pixbuf:pixbuf object
Returns:
The new gdk-pixbuf:pixbuf object, or nil if not enough memory could be allocated for it.
Details:
Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-flip (src horizontal)
Arguments:
src -- a gdk-pixbuf:pixbuf object
horizontal -- true to flip horizontally, false to flip vertically
Details:
Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf.
See also:
#2024-6-29

Utilities

Introduction to utilities

Utility and miscellaneous convenience functions. These functions provide miscellaneous utilities for manipulating pixbufs. The pixel data in pixbufs may of course be manipulated directly by applications, but several common operations can be performed by these functions instead.

Functions for utilities

Function gdk-pixbuf:pixbuf-add-alpha (pixbuf substitute red green blue)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
substitute -- a boolean whether to set a color to zero opacity, if this is false, then the red, green, blue arguments will be ignored
red -- an unsigned char with the red value to substitute
green -- an unsigned char with the green value to substitute
blue -- an unsigned char with the blue value to substitute
Returns:
The newly created pixbuf with a reference count of 1.
Details:
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 the substitute argument is true, then the color specified by red, green, blue will be assigned zero opacity. That is, if you pass (255, 255, 255) for the substitute color, all white pixels will become fully transparent.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-copy-area (src xsrc ysrc width height dest xdest ydest)
Arguments:
src -- a gdk-pixbuf:pixbuf object
xsrc -- an integer with the source x coordinate within src
ysrc -- an integer with the source y coordinate within src
width -- an integer with the width of the area to copy
height -- an integer with the height of the area to copy
dest -- a gdk-pixbuf:pixbuf destination object
xdest -- an integer with the x coordinate within dest
ydest -- an integer with the y coordinate within dest
Details:
Copies a rectangular area from src to dest. 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.
See also:
#2024-6-29
Function gdk-pixbuf:pixbuf-fill (pixbuf pixel)
Arguments:
pixbuf -- a gdk-pixbuf:pixbuf object
pixel -- an unsigned integer for the RGBA pixel to clear to, #xffffffff is opaque white, #x00000000 transparent black
Details:
Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixel format of the pixbuf. The alpha value will be ignored if the pixbuf does not have an alpha channel.
See also:
2025-3-2

Animations

GdkPixbufAnimationIter

Class gdk-pixbuf:pixbuf-animation-iter
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
An opaque object representing an iterator which points to a certain position in an animation.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-iter-pixbuf (iter)
Arguments:
Returns:
The gdk-pixbuf:pixbuf object to be displayed.
Details:
Gets the current pixbuf which should be displayed. The pixbuf might not be the same size as the animation itself which can be get with the gdk-pixbuf:pixbuf-animation-width and the gdk-pixbuf:pixbuf-animation-height functions. This pixbuf should be displayed for a delay time equal to the return value of the gdk-pixbuf:pixbuf-animation-iter-delay-time function.

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 the gdk-pixbuf:pixbuf-animation-iter-advance function. Copy the pixbuf to keep it, do not just add a reference, as it may get recycled as you advance the iterator.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-iter-delay-time (iter)
Arguments:
Returns:
The integer with the delay time in milliseconds.
Details:
Gets the number of milliseconds the current pixbuf should be displayed, or -1 if the current pixbuf should be displayed forever. The g:timeout-add function conveniently takes a timeout in milliseconds, so you can use a timeout to schedule the next update.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-iter-advance (iter time)
Arguments:
time -- an unsigned integer for the current time
Returns:
True if the image may need updating.
Details:
Possibly advances an animation to a new frame. Chooses the frame based on the start time passed to the gdk-pixbuf:pixbuf-animation-iter function.

The time argument would normally come from the g_get_current_time() function, and must be greater than or equal to the time passed to the gdk-pixbuf:pixbuf-animation-iter function, and must increase or remain unchanged each time the gdk-pixbuf:pixbuf-animation-iter-pixbuf function is called. That is, you cannot go backward in time, animations only play forward.

As a shortcut, pass 0 for the current time and the g_get_current_time() function will be invoked on your behalf. So you only need to explicitly pass time if you are doing something odd like playing the animation at double speed.

If this function returns false, there is no need to update the animation display, assuming the display had been rendered prior to advancing. If true, you need to call the gdk-pixbuf:pixbuf-animation-iter-pixbuf function and update the display with the new pixbuf.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-iter-on-currently-loading-frame (iter)
Arguments:
Returns:
True if the frame we are on is partially loaded, or the last frame.
Details:
Used to determine how to respond to the "area-updated" signal on the gdk-pixbuf:pixbuf-loader object when loading an animation. The "area-updated" signal is emitted for an area of the frame currently streaming in to the loader. So if you are on the currently loading frame, you need to redraw the screen for the updated area.
See also:
#2025-3-2

GdkPixbufAnimation

Class gdk-pixbuf:pixbuf-animation
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Returned by:
Details:
The gdk-pixbuf:pixbuf library provides a simple mechanism to load and represent animations. An animation is conceptually a series of frames to be displayed over time. The animation may not be represented as a series of frames internally. For example, it may be stored as a sprite and instructions for moving the sprite around a background. To display an animation you do not need to understand its representation, however. You just ask the gdk-pixbuf:pixbuf object what should be displayed at a given point in time.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-new-from-file (path)
Arguments:
path -- a pathname or namestring for the file to load, in the GLib file name encoding
Returns:
The newly created gdk-pixbuf:pixbuf-animation object, or nil if any of several error conditions ocurred: the file could not be opened, there was no loader for the format of the file, there was not enough memory to allocate the image buffer, or the image file contained invalid data.
Details:
Creates a new animation by loading it from a file. The file format is detected automatically. If the format of the file does not support multi-frame images, then an animation with a single frame will be created.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-new-from-resource (resource)
Arguments:
resource -- a string for the path of the resource file
Returns:
The newly created gdk-pixbuf:pixbuf-animation object, or nil 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.
Details:
Creates a new pixbuf animation by loading an image from an resource. The file format is detected automatically.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-width (animation)
Arguments:
animation -- a gdk-pixbuf:pixbuf-animation object
Returns:
The integer with the width of the bounding box of the animation.
Details:
Queries the width of the bounding box of a pixbuf animation.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-height (animation)
Arguments:
animation -- a gdk-pixbuf:pixbuf-animation object
Returns:
The integer with the height of the bounding box of the animation.
Details:
Queries the width of the bounding box of a pixbuf animation.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-iter (animation time)
Arguments:
animation -- a gdk-pixbuf:pixbuf-animation object
start -- an unsigned integer for the time the animations starts playing
Returns:
The gdk-pixbuf:pixbuf-animation-iter object with the iterator to move over the animation.
Details:
Get an iterator for displaying an animation. The iterator provides the frames that should be displayed at a given time.

The time argument would normally come from the g_get_current_time() function, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by the gdk-pixbuf:pixbuf-animation-iter-pixbuf function. Then, you should install a timeout, with the g:timeout-add function, or by some other mechanism ensure that you will update the image after gdk-pixbuf:pixbuf-animation-iter-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 the time argument is 0, the result of the g_get_current_time() function will be used automatically.

To update the image, that is possibly change the result of the gdk-pixbuf:pixbuf-animation-iter-pixbuf function to a new frame of the animation, call the gdk-pixbuf:pixbuf-animation-iter-advance function.

If you are using the gdk-pixbuf:pixbuf-loader API, in addition to updating the image after the delay time, you should also update it whenever you receive the "area-updated" signal and the gdk-pixbuf:pixbuf-animation-iter-on-currently-loading-frame function 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'.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-animation-is-static-image (animation)
Arguments:
animation -- a gdk-pixbuf:pixbuf-animation object
Returns:
True if the animation was really just an image.
Details:
If you load a file with the gdk-pixbuf:pixbuf-animation-new-from-file function and it turns out to be a plain, unanimated image, then this function will return true. Use the gdk-pixbuf:pixbuf-animation-static-image function to retrieve the image.
See also:
#2025-3-2
Function gdk-pixbuf:pixbuf-animation-static-image (animation)
Arguments:
animation -- a gdk-pixbuf:pixbuf-animation object
Returns:
Unanimated gdk-pixbuf:pixbuf image representing the animation.
Details:
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 has not loaded any frames yet, this function will return nil.
See also:
#2025-3-2

GdkPixbufSimpleAnim

Class gdk-pixbuf:pixbuf-simple-anim
Superclasses:
gdk-pixbuf:pixbuf-animation, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
loop
The loop property of type :boolean (Read / Write)
Whether the animation should loop when it reaches the end.
Default value: false
Returned by:
Slot Access Functions:
Details:
An opaque structure representing a simple animation.
See also:
2025-3-2
Accessor gdk-pixbuf:pixbuf-simple-anim-loop (object)
Syntax:
(gdk-pixbuf:pixbuf-simple-anim-loop object) => loop
(setf (gdk-pixbuf:pixbuf-simple-anim-loop object) loop)
Arguments:
loop -- a boolean whether the animation should loop
Details:
Accessor of the loop slot of the gdk-pixbuf:pixbuf-simple-anim class. Whether the animation should loop when it reaches the end.
See also:
#2025-3-2
Function gdk-pixbuf:pixbuf-simple-anim-new (width height rate)
Arguments:
width -- an integer for the width of the animation
height -- an integer for the height of the animation
rate -- a number coerced to a single float for the speed of the animation, in frames per second
Returns:
The newly allocated gdk-pixbuf:pixbuf-simple-anim object.
Details:
Creates a new, empty animation.
See also:
2025-3-2
Function gdk-pixbuf:pixbuf-simple-anim-add-frame (animation pixbuf)
Arguments:
animation -- a gdk-pixbuf:pixbuf-simple-anim object
pixbuf -- a gdk-pixbuf:pixbuf object to add
Details:
Adds a new frame to animation. The pixbuf must have the dimensions specified when the animation was constructed.
See also:
#2025-3-2

GdkPixbufLoader

Class gdk-pixbuf:pixbuf-loader
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gdk-pixbuf:pixbuf-loader class provides a way for applications to drive the process of loading an image, by letting them send the image data directly to the loader instead of having the loader read the data from a file. Applications can use this functionality instead of the gdk-pixbuf:pixbuf-new-from-file or gdk-pixbuf:pixbuf-animation-new-from-file functions when they need to parse image data in small chunks. For example, it should be used when reading an image from a (potentially) slow network connection, or when loading an extremely large file.

To use the gdk-pixbuf:pixbuf-loader class to load an image, just create a new one, and call the gdk-pixbuf:pixbuf-loader-write function to send the data to it. When done, the gdk-pixbuf:pixbuf-loader-close function should be called to end the stream and finalize everything. The loader will emit three important signals throughout the process. The first, the "size-prepared" signal, will be called as soon as the image has enough information to determine the size of the image to be used. If you want to scale the image while loading it, you can call the gdk-pixbuf:pixbuf-loader-set-size function in response to this signal.

The second signal, the "area-prepared" signal, will be called as soon as the pixbuf of the desired has been allocated. You can obtain it by calling the gdk-pixbuf:pixbuf-loader-pixbuf function. In addition, no actual information will be passed in yet, so the pixbuf can be safely filled with any temporary graphics (or an initial color) as needed. You can also call the gdk-pixbuf:pixbuf-loader-pixbuf function later and get the same pixbuf.

The last signal, the "area-updated" signal gets called every time a region is updated. This way you can update a partially completed image. Note that you do not know anything about the completeness of an image from the area updated. For example, in an interlaced image, you need to make several passes before the image is done loading.

Loading an animation
Loading an animation is almost as easy as loading an image. Once the first "area-prepared" signal has been emitted, you can call the gdk-pixbuf:pixbuf-loader-animation function to get the gdk-pixbuf:pixbuf-animation object and the gdk-pixbuf:pixbuf-animation-iter function to get an gdk-pixbuf:pixbuf-animation-iter object for displaying it.
Signal Details:
The "area-prepared" signal
lambda (loader)    :run-last      
loader
The gdk-pixbuf:pixbuf-loader object which received the signal.
The signal is emitted when the pixbuf loader has allocated the pixbuf in the desired size. After this signal is emitted, applications can call the gdk-pixbuf:pixbuf-loader-pixbuf function to fetch the partially- loaded pixbuf.
The "area-updated" signal
lambda (loader x y width height)    :run-last      
loader
The gdk-pixbuf:pixbuf-loader object which received the signal.
x
The integer with the x offset of upper-left corner of the updated area.
y
The integer with the y offset of upper-left corner of the updated area.
width
The integer with the width of updated area.
height
The integer with the height of updated area.
The 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.
The "closed" signal
lambda (loader)    :run-last      
loader
The gdk-pixbuf:pixbuf-loader object which received the signal.
The signal is emitted when the gdk-pixbuf:pixbuf-loader-close function 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.
The "size-prepared" signal
lambda (loader width height)    :run-last      
loader
The gdk-pixbuf:pixbuf-loader object which received the signal.
width
The integer with the original width of the image.
height
The integer with the original height of the image.
The 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 the gdk-pixbuf:pixbuf-loader-set-size function in response to this signal to set the desired size to which the image should be scaled.
See also:
2025-3-1
Function gdk-pixbuf:pixbuf-loader-new ()
Returns:
The newly created gdk-pixbuf:pixbuf-loader object.
Details:
Creates a new pixbuf loader object.
See also:
2025-3-1
Function gdk-pixbuf:pixbuf-loader-write (loader buffer count)
Arguments:
loader -- a gdk-pixbuf:pixbuf-loader object
buffer -- a Lisp array for image data
count -- an integer for the length of buffer in bytes
Returns:
True if the write was successful, or false if the loader cannot parse the buffer.
Details:
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.
Examples:
A code fragment, which writes data into the pixbuf loader:
;; Create the image stream and the GdkPixbufLoader
(setf stream
      (open (sys-path "alphatest.png")
            :element-type '(unsigned-byte 8)))
(setf loader (gdk-pixbuf:pixbuf-loader-new))

...

(let* ((buffer (make-array 128 :element-type '(unsigned-byte 8))) (len (read-sequence buffer stream))) ... ;; Load the buffer into GdkPixbufLoader (gdk-pixbuf:pixbuf-loader-write loader buffer 128) ... )
See also:
2025-3-1
Function gdk-pixbuf:pixbuf-loader-set-size (loader width height)
Arguments:
loader -- a gdk-pixbuf:pixbuf-loader object
width -- an integer for the desired width of the image being loaded
height -- an integer for the desired height of the image being loaded
Details:
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 the gdk-pixbuf:pixbuf-loader-set-size function 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.
See also:
#2025-3-1
Function gdk-pixbuf:pixbuf-loader-pixbuf (loader)
Arguments:
loader -- a gdk-pixbuf:pixbuf-loader object
Returns:
The gdk-pixbuf:pixbuf object that the loader is creating, or nil if not enough data has been read to determine how to create the image buffer.
Details:
Queries the gdk-pixbuf:pixbuf object 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 the gdk-pixbuf:pixbuf-loader-write function, then this function returns nil. The returned pixbuf will be the same in all future calls to the loader. Additionally, if the loader is an animation, it will return the "static image" of the animation, see the gdk-pixbuf:pixbuf-animation-static-image function.
See also:
2025-3-1
Function gdk-pixbuf:pixbuf-loader-animation (loader)
Arguments:
loader -- a gdk-pixbuf:pixbuf-loader object
Returns:
The gdk-pixbuf:pixbuf-animation object that the loader is loading, or nil if not enough data has been read to determine the information.
Details:
Queries the gdk-pixbuf:pixbuf-animation object 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 does not have enough bytes yet, has not emitted the "area-prepared" signal, this function will return nil.
See also:
#2025-3-1
Function gdk-pixbuf:pixbuf-loader-close (loader)
Arguments:
loader -- a gdk-pixbuf:pixbuf-loader object
Returns:
True if all image data written so far was successfully passed out via the "update-area" signal.
Details:
Informs a pixbuf loader that no further writes with the gdk-pixbuf:pixbuf-loader-write function will occur, so that it can free its internal loading structures. Also, tries to parse any data that has not yet been parsed.
See also:
2025-3-1

Module Interface

CStruct gdk-pixbuf:pixbuf-format
Details:
The gdk-pixbuf:pixbuf-format structure contains information about the image format accepted by a module. Only modules should access the fields directly, applications should use the gdk-pixbuf:pixbuf-format-* functions.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-formats ()
Returns:
The list of gdk-pixbuf:pixbuf-format instances describing the supported image formats.
Details:
Obtains the available information about the image formats supported by the gdk-pixbuf:pixbuf API.
Example:
(mapcar #'gdk-pixbuf:pixbuf-format-name (gdk-pixbuf:pixbuf-formats))
=> ("wmf" "ani" "bmp" "gif" "icns" "ico" "jpeg" "png" "pnm"
    "qtif" "svg" "tga" "tiff" "xbm" "xpm")    
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-name (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The string with the name of the image format.
Details:
Returns the name of the image format.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-description (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The string with a description of the image format.
Details:
Returns a description of the image format.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-mime-types (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The list of strings with the MIME types.
Details:
Returns the MIME types supported by the image format.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-extensions (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The list of strings with filename extensions.
Details:
Returns the filename extensions typically used for files in the given image format.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-is-save-option-supported (format option)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
option -- a string with the name of an option
Returns:
True if the specified option is supported.
Details:
Returns true if the save option specified by option is supported when saving a pixbuf using the module implementing the image format. See the gdk-pixbuf:pixbuf-save function for more information about option keys.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-is-writable (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The boolean whether pixbufs can be saved in the given image format.
Details:
Returns whether pixbufs can be saved in the given image format.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-is-scalable (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The boolean whether this image format is scalable.
Details:
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.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-is-disabled (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The boolean whether this image format is disabled.
Details:
Returns whether this image format is disabled. See the gdk-pixbuf:pixbuf-format-set-disabled function.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-set-disabled (format disabled)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
disabled -- true to disable the given image format
Returns:
The boolean whether this image format is disabled.
Details:
Disables or enables an image format. If the image format is disabled, the gdk-pixbuf:pixbuf library will not use the image loader for this image format to load images. Applications can use this to avoid using image loaders with an inappropriate license, see the gdk-pixbuf:pixbuf-format-license function.
See also:
2024-5-31
Function gdk-pixbuf:pixbuf-format-license (format)
Arguments:
format -- a gdk-pixbuf:pixbuf-format instance
Returns:
The string describing the license of the image format.
Details:
Returns information about the license of the image loader for the image format. The returned string should be a shorthand for a wellknown license, for example, "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license.
See also:
2024-5-31

Package glib

GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. It works on many UNIX-like platforms, as well as Windows and OS X. GLib is released under the GNU Library General Public License (GNU LGPL).

This is the API documentation of a Lisp binding to the library GLib. Only a small part of GLib is implemented in Lisp which is necessary to implement GTK in Lisp.

Version Information

Constant glib:+major-version+
Details:
The major version number of the GLib C library against which the Lisp binding is running.
See also:
2024-10-12
Constant glib:+minor-version+
Details:
The minor version number of the GLib C library against which the Lisp binding is running.
See also:
2024-10-12
Constant glib:+micro-version+
Details:
The micro version number of the GLib C library against which the Lisp binding is running.
See also:
2024-10-12
Function glib:check-version (major minor micro)
Arguments:
major -- an unsigned integer with the required major version
minor -- an unsigned integer with the required minor version
micro -- an unsigned integer with the required micro version
Returns:
Returns nil if the GLib C library against which the Lisp binding is running is compatible with the given version, or a string describing the version mismatch.
Details:
Checks if the GLib C library that is used is compatible with the given Lisp binding.
Examples:
Suppose the Glib library version 2.72.1 is installed. Then the following results are returned:
(glib:check-version 2 72 0) => NIL
(glib:check-version 2 99 0) => "GLib version too old (micro mismatch)"    
See also:
2024-10-12
Function glib:cl-cffi-glib-build-info (&optional out)
Arguments:
out -- an optional stream, the default is *standard-output*
Details:
Provides information about the version of the loaded GLIB library against which the Lisp binding is running.
Examples:
* (g:cl-cffi-glib-build-info)
cl-cffi-glib build date: 20:48 11/6/2024
GLIB version: 2.82.1
Machine type: X86-64
Machine version: Intel(R) Core(TM) i5-5200U CPU @ 2.20GHz
Software type: Linux
Software version: 6.11.0-8-generic
Lisp implementation type: SBCL
Lisp implementation version: 2.2.9.debian
NIL    
See also:
2024-10-12

Miscellaneous

Introduction to miscellaneous

Documentation of several type definitions and functions, which are needed for the implementation of the GTK library. Only a small part of the GLib library is implemented.

String Utility Functions

Type glib:strv-t
Details:
The g:strv-t type specifier represents and performs automatic conversion between a list of Lisp strings and an array of C strings of the CFFI :string type.
Examples:
(setq str (cffi:convert-to-foreign (list "Hello" "World") 'g:strv-t))
=> #.(SB-SYS:INT-SAP #X01541998)
(cffi:convert-from-foreign str 'g:strv-t)
=> ("Hello" "World")    
2024-10-12

Doubly-Linked Lists

Type glib:list-t
Details:
The g:list-t type specifier represents a C doubly linked list with elements of the GList structure. The g:list-t type specifier performs automatic conversion from a C list to a Lisp list. The elements of the list can be pointers, strings or GObjects.
Examples:
(cffi:convert-to-foreign (list "a" "b" "c") '(g:list-t :string))
=> #.(SB-SYS:INT-SAP #X03B92220)
(cffi:convert-from-foreign * '(g:list-t :string))
=> ("a" "b" "c")    
See also:
2024-10-12

Singly-Linked Lists

Type glib:slist-t
Details:
The g:slist-t type specifier represents a C singly linked list with elements of the GSList structure. The g:slist-t type specifier performs automatic conversion from a C list to a Lisp list. The elements of the list can be pointers, strings or GObjects.
Examples:
(cffi:convert-to-foreign (list "a" "b" "c") '(g:slist-t :string))
=> #.(SB-SYS:INT-SAP #X03B92220)
(cffi:convert-from-foreign * '(g:slist-t :string))
=> ("a" "b" "c")    
See also:
2024-10-12

Quarks

Type glib:quark-as-string
Details:
Quarks are associations between strings and integer identifiers. Given either the string or the GQuark identifier it is possible to retrieve the other.
Lisp binding:
In the Lisp binding the g:quark-as-string type specifier translates a string argument to the corresponding GQuark identifier and a GQuark return value is translated to the corresponding Lisp string. No further functions are implemented for the g:quark-as-string type specifier.

If the Lisp string does not currently has an associated GQuark, a new GQuark is created. A GQuark value of zero is associated to nil in Lisp.

See the g:type-qdata function for attaching a GQuark identifier to a g:type-t type ID.
Examples:
Translate a Lisp String to a GQuark identifier:
(cffi:convert-to-foreign "GtkWidget" 'g:quark-as-string) => 91
(cffi:convert-to-foreign "gboolean" 'g:quark-as-string) => 9
(cffi:convert-to-foreign nil 'g:quark-as-string) => 0     
Translate a GQuark identifier to a Lisp string:
(cffi:convert-from-foreign 91 'g:quark-as-string) => "GtkWidget"
(cffi:convert-from-foreign 9 'g:quark-as-string) => "gboolean"
(cffi:convert-from-foreign 0 'g:quark-as-string) => NIL     
See also:
2024-10-12

GDateTime

Type glib:date-time
Details:
The g:date-time type specifier represents the C GDateTime type which represents a date and time. The g:date-time type specifier performs automatic conversion between the GDateTime time representation and the Lisp universal time, that is measured as an offset from the beginning of the year 1900.
Examples:
(cffi:convert-to-foreign 0 'g:date-time)
=> #.(SB-SYS:INT-SAP #X558E3298CE40)
(cffi:convert-from-foreign * 'g:date-time) => 0    
2024-12-18

Unicode manipulation

Type glib:unichar
Details:
The g:unichar type specifier represents the C gunichar type which can hold any UCS-4 character code. The g:unichar type specifier performs automatic conversion from the C gunichar type to a Lisp character and a Lisp character to the C type. An integer as argument to the cffi:convert-to-foreign function is passed through.
Examples:
Convert a Lisp character to a C gunichar value:
(cffi:convert-to-foreign #A 'g:unichar) => 65
(cffi:convert-to-foreign #0 'g:unichar) => 48
(cffi:convert-to-foreign #return 'g:unichar) => 13
(cffi:convert-to-foreign #space 'g:unichar) => 32    
Convert a C gunichar value to a Lisp character:
(cffi:convert-from-foreign 65 'g:unichar) => #A
(cffi:convert-from-foreign 48 'g:unichar) => #0
(cffi:convert-from-foreign 13 'g:unichar) => #return
(cffi:convert-from-foreign 32 'g:unichar) => #space    
An integer argument is passed through:
(cffi:convert-to-foreign 65 'g:unichar) => 65    
2024-10-12

GError

GBoxed glib:error
Declaration:
(define-gboxed-opaque error "GError"
  :export t
  :type-initializer "g_error_get_type"
  :alloc (cl:error "GError cannot be created from the Lisp side."))  
Details:
The glib:error structure contains information about an error that has occurred.
2023-6-1

Memory Allocation

Function glib:malloc (nbytes)
Arguments:
nbytes -- an integer of :size type with the number of bytes to allocate
Returns:
The foreign pointer to the allocated memory.
Details:
Allocates nbytes bytes of memory. If the nbytes argument is 0 the g:malloc function returns a foreign cffi:null-pointer value.
Examples:
(g:malloc 100)
=> #.(SB-SYS:INT-SAP #X559FB7283340)
(g:malloc 0)
=> #.(SB-SYS:INT-SAP #X00000000)
(cffi:null-pointer-p (g:malloc 0))
=> T    
See also:
2024-10-12
Function glib:free (mem)
Arguments:
mem -- a foreign pointer to the memory to free
Details:
Frees the memory pointed to by the mem foreign pointer. If the mem argument is a foreign cffi:null-pointer the g:free function simply returns.
See also:
2024-10-12

Utility Functions

Function glib:application-name ()
Syntax:
(g:application-name) => name
(setf (g:application-name) name)
Arguments:
name -- a string with the localized name of the application
Details:
Accessor of a human readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with the g:prgname function, which gets a non-localized name. If the (setf g:application-name) function has not been called, returns the result of the g:prgname function, which may be nil if the (setf g:prgname) function has also not been called.

The g:prgname function will be called automatically by gtk_init(), but the g:application-name function will not. Note that for thread safety reasons, this function can only be called once.

The application name will be used in contexts such as error messages, or when displaying the name of an application in the task list.
See also:
2024-10-12
Function glib:prgname ()
Syntax:
(g:prgname) => prgname
(setf (g:prgname) prgname)
Arguments:
prgname -- a string with the name of the program
Details:
Accessor of the name of the program. This name should not be localized, contrast with the g:application-name function. If you are using GDK or GTK the program name is set in the gdk_init() function, which is called by the gtk_init() function. The program name is found by taking the last component of the first command line argument.

Note that for thread-safety reasons this function can only be called once.
See also:
2024-10-12

The Main Event Loop

GMainLoop

Constant glib:+priority-high+
Initial Value:
-100
Details:
Use this for high priority event sources. It is not used within GLib or GTK.
See also:
2024-4-2
Constant glib:+priority-default+
Initial Value:
0
Details:
Use this for default priority event sources. In GLib this priority is used when adding timeout functions with the g:timeout-add function. In GDK this priority is used for events from the X server.
See also:
2024-4-2
Constant glib:+priority-high-idle+
Initial Value:
100
Details:
Use this for high priority idle functions. GTK uses the g:+priority-high-idle+ + 10 value for resizing operations, and the g:+priority-high-idle+ + 20 value for redrawing operations. This is done to ensure that any pending resizes are processed before any pending redraws, so that widgets are not redrawn twice unnecessarily.
See also:
2024-4-2
Constant glib:+priority-default-idle+
Initial Value:
200
Details:
Use this for default priority idle functions. In GLib this priority is used when adding idle functions with the g:idle-add function.
See also:
2024-4-2
Constant glib:+priority-low+
Initial Value:
300
Details:
Use this for very low priority background tasks. It is not used within GLib or GTK.
See also:
2024-4-2
Constant glib:+source-continue+
Initial Value:
true
Details:
Use this constant as the return value of a g:source-func callback function to leave the g:source instance in the main loop.
See also:
2024-4-2
Constant glib:+source-remove+
Initial Value:
false
Details:
Use this constant as the return value of a g:source-func callback function to remove the g:source instance from the main loop.
See also:
2024-4-2
CStruct glib:main-loop
Returned by:
Details:
The main event loop manages all the available sources of events for GLib and GTK applications. These events can come from any number of different types of sources such as file descriptors (plain files, pipes or sockets) and timeouts. New types of event sources can also be added using the g:source-attach function.

To allow multiple independent sets of sources to be handled in different threads, each source is associated with a g:main-context instance. A g:main-context instance can only be running in a single thread, but sources can be added to it and removed from it from other threads. All functions which operate on a g:main-context instance or a built-in g:source instance are thread-safe.

Each event source is assigned a priority. The g:+priority-default+ default priority, is 0. Values less than 0 denote higher priorities. Values greater than 0 denote lower priorities. Events from high priority sources are always processed before events from lower priority sources.

Idle functions can also be added, and assigned a priority. These will be run whenever no events with a higher priority are ready to be processed.

The g:main-loop structure represents a main event loop. A g:main-loop instance is created with the g:main-loop-new function. After adding the initial event sources, the g:main-loop-run function is called. This continuously checks for new events from each of the event sources and dispatches them. Finally, the processing of an event from one of the sources leads to a call to the g:main-loop-quit funcion to exit the main loop, and the g:main-loop-run function returns.

It is possible to create new instances of the g:main-loop structure recursively. This is often used in GTK applications when showing modal dialog boxes. Note that event sources are associated with a particular g:main-context instance, and will be checked and dispatched for all main loops associated with that g:main-context instance.
See also:
2024-11-6
Function glib:main-loop-new (context is-running)
Arguments:
context -- a g:main-context instance, if nil, the default context will be used
is-running -- set to true to indicate that the main loop is running
Returns:
The new g:main-loop instance.
Details:
Creates a new main loop.
Examples:
Create a running main loop with a default context and quit the main loop.
(setq mainloop (g:main-loop-new nil t))
=> #.(SB-SYS:INT-SAP #X0808DF88)
(g:main-loop-is-running mainloop) => T
(g:main-loop-quit mainloop)
(g:main-loop-is-running mainloop) => NIL    
See also:
2024-11-6
Function glib:main-loop-ref (loop)
Arguments:
loop -- a g:main-loop instance
Returns:
The loop argument.
Details:
Increases the reference count on a main loop by one.
See also:
2024-11-6
Function glib:main-loop-unref (loop)
Arguments:
loop -- a g:main-loop instance
Details:
Decreases the reference count on a main loop by one. If the result is zero, free loop and free all associated memory.
See also:
2024-11-6
Function glib:main-loop-run (loop)
Arguments:
loop -- a g:main-loop instance
Details:
Runs a main loop until the g:main-loop-quit function is called on the main loop. If this is called for the thread of the context of the main loop, it will process events from the main loop, otherwise it will simply wait.
See also:
2024-11-6
Function glib:main-loop-quit (loop)
Arguments:
loop -- a g:main-loop instance
Details:
Stops a main loop from running. Any calls to the g:main-loop-run function for the main loop will return. Note that sources that have already been dispatched when the g:main-loop-quit function is called will still be executed.
See also:
2024-11-6
Function glib:main-loop-is-running (loop)
Arguments:
loop -- a g:main-loop instance
Returns:
True if the main loop is currently being run.
Details:
Checks to see if the main loop is currently being run via the g:main-loop-run function.
See also:
2024-11-6
Function glib:main-loop-context (loop)
Arguments:
loop -- a g:main-loop instance
Returns:
The g:main-context instance of loop.
Details:
Returns the context of the main loop.
See also:
2024-11-6

GMainContext

CStruct glib:main-context
Returned by:
Details:
The g:main-context structure is an opaque data type representing a set of sources to be handled in a main loop.
See also:
2024-11-6
Function glib:main-context-new ()
Returns:
The new g:main-context instance.
Details:
Creates a new context.
See also:
2024-11-6
Function glib:main-context-ref (context)
Arguments:
context -- a g:main-context instance
Returns:
The context argument.
Details:
Increases the reference count on a context by one.
See also:
2024-11-6
Function glib:main-context-unref (context)
Arguments:
context -- a g:main-context instance
Details:
Decreases the reference count on a context by one. If the result is zero, free context and free all associated memory.
See also:
2024-11-6
Function glib:main-context-default ()
Returns:
The g:main-context instance with the global default context.
Details:
Returns the global default context. This is the context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop.
See also:
2024-11-6
Function glib:main-context-iteration (context block)
Arguments:
context -- a g:main-context instance, if nil, the default context will be used
block -- a boolean whether the call may block
Returns:
True if events were dispatched.
Details:
Runs a single iteration for the given main loop. This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and the block argument is true, waiting for a source to become ready, then dispatching the highest priority events sources that are ready. Otherwise, if the block argument is false sources are not waited to become ready, only those highest priority events sources will be dispatched (if any), that are ready at this given moment without further waiting.

Note that even when the block argument is true, it is still possible for the g:main-context-iteration function to return false, since the wait may be interrupted for other reasons than an event source becoming ready.
See also:
#2024-11-6
Function glib:main-context-pending (context)
Arguments:
context -- a g:main-context instance, if nil, the default context will be used
Returns:
True if events are pending.
Details:
Checks if any sources have pending events for the given main context.
See also:
#2024-11-6
Function glib:main-context-find-source-by-id (context source)
Arguments:
context -- a g:main-context instance, if nil, the default context will be used
source -- an unsigned integer source ID, as returned by the g:source-id function
Returns:
The g:source instance if found, otherwise nil.
Details:
Finds a source given a pair of context and ID. It is a programmer error to attempt to look up a non-existent source. More specifically, source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with the g:idle-add function. The idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source.
See also:
2024-11-6
Function glib:main-context-is-owner (context)
Arguments:
context -- a g:main-context instance
Returns:
True if the current thread is owner of context.
Details:
Determines whether this thread holds the (recursive) ownership of this context. This is useful to know before waiting on another thread that may be blocking to get ownership of context.
See also:
2024-11-6

GSource

CStruct glib:source
Details:
The g:source structure is an opaque data type representing an event source.
See also:
2024-11-6
Function glib:timeout-source-new (interval)
Arguments:
interval -- an integer with the timeout interval in milliseconds
Returns:
The newly created g:source timeout source.
Details:
Creates a new timeout source. The source will not initially be associated with any context and must be added to one with the g:source-attach function before it will be executed.
See also:
2024-11-6
Function glib:timeout-source-new-seconds (interval)
Arguments:
interval -- an integer with the timeout interval in seconds
Returns:
The newly created g:source timeout source.
Details:
Creates a new timeout source. The source will not initially be associated with any context and must be added to one with the g:source-attach function before it will be executed. The scheduling granularity/accuracy of this timeout source will be in seconds.
See also:
2024-11-6
Function glib:timeout-add (interval func &key priority)
Arguments:
interval -- an integer for the time between calls to func, in milliseconds
func -- a g:source-func callback function to call
priority -- an integer for the priority of the timeout source, typically this will be in the range between the g:+priority-default+ and g:+priority-high+ values
Returns:
The unsigned integer ID greater than 0 for the event source.
Details:
Sets a function to be called at regular intervals, with priority. The default value is g:+priority-default+. The function is called repeatedly until it returns false, at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval. It does not try to 'catch up' time lost in delays.

If you want to have a timer in the "seconds" range and do not care about the exact time of the first call of the timer, use the g:timeout-add-seconds function. This function allows for more optimizations and more efficient system power usage.

This internally creates a main loop source using the g:timeout-source-new function and attaches it to the main loop context using the g:source-attach function. You can do these steps manually if you need greater control.
See also:
2025-3-1
Function glib:timeout-add-seconds (interval func &key priority)
Arguments:
interval -- an unsigned integer with the time between calls to func, in seconds
func -- a g:source-func callback function to call
priority -- an integer with the priority of the timeout source, typically this will be in the range between g:+priority-default+ and g:+priority-high+ values
Returns:
The unsigned integer ID greater than 0 of the event source.
Details:
Sets a function to be called at regular intervals with priority. The default value is g:+priority-default+. The function is called repeatedly until it returns false, at which point the timeout is automatically destroyed and the function will not be called again.

This internally creates a main loop source using the g:timeout-source-new-seconds function and attaches it to the main loop context using the g:source-attach function. You can do these steps manually if you need greater control.

Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, you may want to use the g:timeout-add function instead.
See also:
2024-11-6
Function glib:idle-source-new ()
Returns:
The newly created g:source idle source.
Details:
Creates a new idle source. The source will not initially be associated with any context and must be added to one with the g:source-attach function before it will be executed. Note that the default priority for idle sources is g:+priority-default-idle+, as compared to other sources which have a default priority of g:+priority-default+.
See also:
2024-11-6
Function glib:idle-add (func &key priority)
Arguments:
func -- a g:source-func callback function to call
priority -- an integer with the priority of the idle source, typically this will be in the range between g:+priority-default-idle+ and g:+priority-high-idle+
Returns:
The unsigned integer ID greater than 0 of the event source.
Details:
Adds a function to be called whenever there are no higher priority events pending to the default main loop. The priority keyword argument has the g:+priority-default-idle+ default value. If the function returns false it is automatically removed from the list of event sources and will not be called again.

This internally creates a main loop source using the g:idle-source-new function and attaches it to the main loop context using the g:source-attach function. You can do these steps manually if you need greater control.
See also:
2024-11-6
Function glib:source-attach (source context)
Arguments:
source -- a g:source instance
context -- a g:main-context instance, if nil, the default context will be used
Returns:
The unsigned integer ID greater than 0 for the source within context.
Details:
Adds a source to a context so that it will be executed within that context. Remove it by calling the g:source-destroy function.
See also:
2024-11-6
Function glib:source-destroy (source)
Arguments:
source -- a g:source instance
Details:
Removes a source from its context, if any, and mark it as destroyed. The source cannot be subsequently added to another context.
See also:
2024-11-6
Function glib:source-is-destroyed (source)
Arguments:
source -- a g:source instance
Returns:
True if source has been destroyed.
Details:
Returns whether the source has been destroyed. This is important when you operate upon your objects from within idle handlers, but may have freed the object before the dispatch of your idle handler.
See also:
2024-11-6
Function glib:source-priority (source)
Syntax:
(g:source-priority source) => priority
(setf (g:source-priority source) => priority)
Arguments:
source -- a g:source instance
priority -- an integer with the priority
Details:
The g:source-priority function gets the priority of the source. The (setf g:source-priority) function sets the priority. While the main loop is being run, a source will be dispatched if it is ready to be dispatched and no sources at a higher (numerically smaller) priority are ready to be dispatched.
See also:
2024-11-6
Function glib:source-can-recurse (source)
Syntax:
(g:source-can-recurse source) => can-recurse
(setf g:source-can-recurse source) can-recurse)
Arguments:
source -- a g:source instance
can-recurse -- a boolean whether recursion is allowed for this source
Details:
The g:source-can-recurse function checks whether the source is allowed to be called recursively. The (setf g:source-can-recurse) function sets whether the source can be called recursively. If the can-recurse argument is true, then while the source is being dispatched then this source will be processed normally. Otherwise, all processing of this source is blocked until the dispatch function returns.
See also:
2024-11-6
Function glib:source-id (source)
Arguments:
source -- a g:source instance
Returns:
The unsigned integer with the ID greater than 0 for source.
Details:
Returns the numeric ID for a particular source. The ID of a source is a positive integer which is unique within a particular main loop context. The reverse mapping from ID to source is done by the g:main-context-find-source-by-id function.
See also:
2024-11-6
Function glib:source-name (source)
Syntax:
(g:source-name source) => name
(setf (g:source-name source) name)
Arguments:
source -- a g:source instance
name -- a string with the debug name for the source
Details:
The g:source-name function gets a name for the source, used in debugging and profiling. The (setf g:source-name) function sets a name for the source. The name may be nil. The source name should describe in a human readable way what the source does. For example, "X11 event queue" or "GTK repaint idle handler" or whatever it is.

It is permitted to call this function multiple times, but is not recommended due to the potential performance impact. For example, one could change the name in the g:source-func callback function to include details like the event type in the source name.
See also:
2024-11-6
Function glib:source-set-name-by-id (source name)
Arguments:
source -- an integer with the source ID
name -- a string with the debug name for the source
Details:
Sets the name of a source using its ID. This is a convenience utility to set source names from the return value of the g:idle-add, g:timeout-add functions, and so on.
See also:
2024-11-6
Function glib:source-context (source)
Arguments:
source -- a g:source instance
Returns:
The g:main-context instance with which the source is associated, or nil if the context has not yet been added to a source.
Details:
Gets the context with which the source is associated. Calling this function on a destroyed source is an error.
See also:
2024-11-6
Callback glib:source-func
Syntax:
lambda () => result
Arguments:
result -- false if the source should be removed, the g:+source-continue+ and g:+source-remove+ constants are memorable names for the return value
Details:
Specifies the type of callback function passed to the g:timeout-add, and g:idle-add functions.
Examples:
This example shows a timeout callback function, which runs 10 times and then quits the main loop.
(let ((counter 0) (max 10))
  (defun timeout-callback (loop)
    (incf counter)
    (if (>= counter max)
        (progn
          ;; Reset the counter
          (setf counter 0)
          ;; Stop the main loop from running
          (g:main-loop-quit loop)
          ;; Stop the source
          g:+source-remove+)
        ;; Continue the source
        g:+source-continue+)))

(defun example-timeout-source () (let* ((context (g:main-context-new)) (mainloop (g:main-loop-new context nil)) ;; Create a new timeout source (source (g:timeout-source-new 10))) ;; Attach source to context (g:source-attach source context) ;; Set the callback for source (g:source-set-callback source (lambda () (timeout-callback mainloop))) ;; Start the main loop (g:main-loop-run mainloop) (g:main-loop-unref mainloop)))
See also:
2024-11-6
Function glib:source-set-callback (source func)
Arguments:
source -- a g:source instance
func -- a g:source-func callback function
Details:
Sets the callback function for a source. The callback function for a source is called from the dispatch function of the source. Typically, you will not use this function. Instead use functions specific to the type of source you are using.
See also:
2024-11-6
Function glib:source-add-child-source (source child)
Arguments:
source -- a g:source instance
child -- a second g:source instance that source should "poll"
Details:
Adds child to source as a "polled" source. When source is added to a g:main-context instance, child will be automatically added with the same priority, when child is triggered, it will cause source to dispatch (in addition to calling its own callback), and when source is destroyed, it will destroy child as well. The source instance will also still be dispatched if its own prepare/check functions indicate that it is ready.

The source instance will hold a reference on child while child is attached to it.
See also:
#2024-11-6
Function glib:source-remove-child-source (source child)
Arguments:
source -- a g:source instance
child -- a g:source instance previously passed to the g:source-add-child-source function
Details:
Detaches child from source and destroys it.
See also:
#2024-11-6
Function glib:source-time (source)
Arguments:
source -- a g:source instance
Returns:
The unsigned integer with the monotonic time in microseconds.
Details:
Gets the time to be used when checking this source. The time here is the system monotonic time, if available, or some other reasonable alternative otherwise.
See also:
2024-11-6
Function glib:source-ready-time (source)
Syntax:
(g:source-ready-time source) => time
(setf (g:source-readey-time source) time)
Arguments:
source -- a g:source instance
time -- an integer with the monotonic time at which the source will be ready, 0 for "immediately", -1 for "never"
Details:
The g:source-ready-time function gets the "ready time" of the source. Any time before the current monotonic time, including 0, is an indication that the source will fire immediately. The (setf g:source-ready-time) function sets a source to be dispatched when the given monotonic time is reached (or passed). If the monotonic time is in the past, as it always will be if time is 0, then the source will be dispatched immediately. If time is -1 then the source is never woken up on the basis of the passage of time. Dispatching the source does not reset the ready time. You should do so yourself, from the source dispatch function.

Note that if you have a pair of sources where the ready time of one suggests that it will be delivered first but the priority for the other suggests that it would be delivered first, and the ready time for both sources is reached during the same main context iteration then the order of dispatch is undefined.
See also:
2024-11-6
Function glib:source-remove (source)
Arguments:
source -- an unsigned integer ID for the source to remove
Returns:
True if source was found and removed.
Details:
Removes the source with the given ID from the default main context. The ID of a g:source instance is given by the g:source-id function, or will be returned by the g:source-attach, g:idle-add, g:timeout-add functions. You must use the g:source-destroy function for sources added to a non-default main context.
See also:
2024-11-6

GBytes

GBoxed glib:bytes
Declaration:
(define-gboxed-opaque bytes "GBytes"
  :export t
  :type-initializer "g_bytes_get_type"
  :alloc (%bytes-new (cffi:null-pointer) 0))  
Returned by:
Details:
The g:bytes structure is a simple refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin. The purpose of a g:bytes instance 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 g:bytes instance without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference.

A g:bytes instance can come from many different origins that may have different procedures for freeing the memory region. Examples are memory from the g:malloc function.
Examples:
Using a g:bytes instance for a Lisp string as byte data.
(multiple-value-bind (data len)
    (foreign-string-alloc "A test string.")
  (defvar bytes (g:bytes-new data len)))
=> BYTES
(g:bytes-size bytes)
=> 15
(g:bytes-data bytes)
=> #.(SB-SYS:INT-SAP #X55EBB2C1DB70)
=> 15
(foreign-string-to-lisp (g:bytes-data bytes))
=> "A test string."
=> 14    
Using a g:bytes instance to allocate the memory for a paintable with 110 x 80 pixels and 4 bytes per pixel.
(let* ((size (* 4 110 80))
       (data (cffi:foreign-alloc :uchar :count size :initial-element #xff))
       (bytes (g:bytes-new data size))
       (texture (gdk:memory-texture-new 110 70
                                        :B8G8R8A8-PREMULTIPLIED
                                        bytes
                                        (* 4 110)))
       (picture (gtk:picture-new-for-paintable texture)))
... )    
2024-11-6
Function glib:bytes-new (data size)
Arguments:
data -- a pointer to the data to be used for the bytes
size -- an integer with the size of data
Returns:
The new g:bytes instance.
Details:
Creates a new g:bytes instance from data.
See also:
2024-11-6
Function glib:bytes-data (bytes)
Arguments:
bytes -- a g:bytes instance
Returns:
data -- a pointer to the byte data, or a cffi:null-pointer value
size -- an integer with the size of the byte data
Details:
Get the byte data in the g:bytes instance. This function will always return the same pointer for a given g:bytes instance.

A cffi:null-pointer value may be returned if the size value is 0. This is not guaranteed, as the g:bytes instance may represent an empty string with data not a cffi:null-pointer value and the size value as 0. A cffi:null-pointer value will not be returned if the size value is non-zero.
See also:
2024-12-29
Function glib:bytes-size (bytes)
Arguments:
bytes -- a g:bytes instance
Returns:
The integer with the size of the byte data.
Details:
Get the size of the byte data in the g:bytes instance. This function will always return the same value for a given g:bytes instance.
See also:
2024-11-6

Command line option parser

CEnum glib:option-arg
Declaration:
(cffi:defcenum option-arg
  :none
  :string
  :int
  :callback
  :filename
  :string-array
  :filename-array
  :double
  :int64)  
Values:
:none
No extra argument. This is useful for simple flags.
:string
The option takes a string argument.
:int
The option takes an integer argument.
:callback
The option provides a callback function to parse the extra argument.
:filename
The option takes a filename as argument.
:string-array
The option takes a string argument, multiple uses of the option are collected into a list of strings.
:filename-array
The option takes a filename as argument, multiple uses of the option are collected into a list of filenames.
:double
The option takes a double float argument. The argument can be formatted either for the locale of the user or for the C locale.
:int64
The option takes a 64-bit integer. Like the :int value but for larger numbers.
Details:
The g:option-arg enumeration determines which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways, with a short option -x arg, with a long option --name arg or combined in a single argument --name=arg.
See also:
2024-11-19
Bitfield glib:option-flags
Declaration:
(cffi:defbitfield option-flags
  :none
  :hidden
  :in-main
  :reverse
  :no-arg
  :filename
  :optional-arg
  :noalias)  
Values:
:none
No flags.
:hidden
The option does not appear in --help output.
:in-main
The option appears in the main section of the --help output, even if it is defined in a group.
:reverse
For options of the :none kind, this flag indicates that the sense of the option is reversed.
:no-arg
For options of the :callback kind, this flag indicates that the callback function does not take any argument, like a :none option.
:filename
For options of the :callback kind, this flag indicates that the argument should be passed to the callback function in the GLib filename encoding rather than UTF-8.
:optional-arg
For options of the :callback kind, this flag indicates that the argument supply is optional. If no argument is given then data of the GOptionParseFunc callback function will be set to NULL.
:noalias
This flag turns off the automatic conflict resolution which prefixes long option names with a group name, if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy command line interface. It is not safe to use this option, unless all option groups are under your direct control.
Details:
Flags which modify individual options.
See also:
2024-11-19
CStruct glib:option-context
Returned by:
Details:
The GOption command line parser is intended to be a simpler replacement for the popt library. It supports short and long command line options, as shown in the following example:
testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2  
The example demonstrates a number of features of the GOption command line parser:
  • Options can be single letters, prefixed by a single dash.
  • Multiple short options can be grouped behind a single dash.
  • Long options are prefixed by two consecutive dashes.
  • Options can have an extra argument, which can be a number, a string or a filename. For long options, the extra argument can be appended with an equals sign after the option name, which is useful if the extra argument starts with a dash, which would otherwise cause it to be interpreted as another option.
  • Non-option arguments are returned to the application as rest arguments.
  • An argument consisting solely of two dashes turns off further parsing, any remaining arguments, even those starting with a dash, are returned to the application as rest arguments.
Another important feature of GOption is that it can automatically generate nicely formatted help output. Unless it is explicitly turned off with the g:option-context-help-enabled function, GOption will recognize the --help, -?, --help-all and --help-groupname options, where groupname is the name of a g:option-group instance, and write a text similar to the one shown in the following example.
Usage:
  testtreemodel [OPTION...] - test tree model performance

Help Options: -h, --help Show help options

Application Options: -r, --repeats=N Average over N repetitions -m, --max-size=M Test up to 2^M items --display=DISPLAY X display to use -v, --verbose Be verbose -b, --beep Beep when done --rand Randomize the data
GOption groups options in a g:option-group instance, which makes it easy to incorporate options from multiple sources. The intended use for this is to let applications collect option groups from the libraries it uses, add them to their g:option-context instance, and parse all options by a single call to the g:option-context-parse function.

If an option is declared to be of type string or filename, GOption takes care of converting it to the right encoding. Strings are returned in UTF-8, filenames are returned in the GLib filename encoding. Note that this only works if the setlocale() function has been called before the g:option-context-parse function.

Here is a complete example of setting up GOption to parse the example command line above and produce the example help output.
(defvar repeats (cffi:foreign-alloc :int :initial-element 2))
(defvar max-size (cffi:foreign-alloc :int :initial-element 0))
(defvar verbose (cffi:foreign-alloc :boolean :initial-element nil))
(defvar beep (cffi:foreign-alloc :boolean :initial-element nil))
(defvar randomize (cffi:foreign-alloc :boolean :initial-element nil))

(defun main (&rest argv) (let ((entries '(("repeats" ; long-name #\r ; short-name :none ; flags :int ; arg repeats ; arg-data "Average over N repetitions" ; description "N") ; arg-description ("max-size" #\m 0 :int max-size "Test up to 2^M items" "M") ("verbose" #\v 0 :none verbose "Be verbose" nil) ("beep" #\b 0 :none beep "Beep when done" nil) ("rand" #\Nul 0 :none randomize "Randomize the data" nil))) (context (g:option-context-new "- test tree model performance"))) ;; Add the option entries to the option context (g:option-context-add-main-entries context entries nil) ;; Parse the commandline argumentens and show the result (if (g:option-context-parse context argv) (progn (format t "Option parsing failed.~%") ;; Print the Help Usage (format t "~&~%~a~%" (g:option-context-help context t))) (progn ;; Print the parsed arguments (format t "~&Parsed arguments~%") (format t " repeats : ~a~%" (cffi:mem-ref repeats :int)) (format t " max-size : ~a~%" (cffi:mem-ref max-size :int)) (format t " verbose : ~a~%" (cffi:mem-ref verbose :boolean)) (format t " beep : ~a~%" (cffi:mem-ref beep :boolean)) (format t " randomize : ~a~%" (cffi:mem-ref randomize :boolean)))) ... ))
On UNIX systems, the argv argument that is passed to the main function has no particular encoding, even to the extent that different parts of it may have different encodings. In general, normal arguments and flags will be in the current locale and filenames should be considered to be opaque byte strings. Proper use of the :filename versus :string option arguments is therefore important.

Note that on Windows, filenames do have an encoding, but using a g:option-context instance with the argv argument as passed to the main function will result in a program that can only accept command line arguments with characters from the system codepage. This can cause problems when attempting to deal with filenames containing Unicode characters that fall outside of the codepage.

A solution to this is to use the g_win32_get_command_line() and g:option-context-parse-strv functions which will properly handle full Unicode filenames. If you are using a g:application instance, this is done automatically for you.
See also:
2024-11-19
Macro glib:with-option-context ((context &rest args) &body body)
Syntax:
(g:with-option-context (context) body) => result
(g:with-option-context (context parameter) body) => result
Arguments:
context -- a g:option-context instance to create and initialize
parameter -- an optional string which is displayed in the first line of --help output
Details:
The g:with-option-context macro allocates a new g:option-context instance, initializes the option context with the optional parameter value and executes the body that uses the context. After execution of the body the allocated memory for the option context is released. See the documentation of the g:option-context-new function for more information about the initialization of the new option context.
See also:
2024-11-19
Function glib:option-context-new (&optional parameter)
Arguments:
parameter -- a string which is displayed in the first line of --help output
Returns:
The newly created g:option-context instance, which must be freed with the g:option-context-free function after use.
Details:
Creates a new option context. The parameter argument can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the g:option-context instance, typically something like "FILES" or "FILE1 FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the arg-description parameter of the corresponding option entry in the usage summary.

Another usage is to give a short summary of the program functionality, like "- frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use the g:option-context-summary function.

Note that the parameter argument is translated using the function set with the g:option-context-set-translate-func function, so it should normally be passed untranslated.
Examples:
(g:option-context-new "This is an example for a description.")
=> #.(SB-SYS:INT-SAP #X0817EB48)
(g:option-context-help * nil)
=>
"Aufruf:
  sbcl [OPTION …] This is an example for a description.

Hilfeoptionen: -h, --help Hilfeoptionen anzeigen "
See also:
2024-11-19
Function glib:option-context-free (context)
Arguments:
context -- a g:option-context instance
Details:
Frees context and all the groups which have been added to it. Please note that parsed arguments need to be freed separately.
See also:
2024-11-19
Function glib:option-context-summary (context)
Syntax:
(g:option-context-summary context) => summary
(setf (g:option-context-summary context) summary)
Arguments:
context -- a g:option-context instance
summary -- a string to be shown in --help output before the list of options, or nil
Details:
The g:option-context-summary function returns the summary. The (setf g:option-context-summary) function adds a string to be displayed in --help output before the list of options. This is typically a summary of the program functionality.

Note that the summary is translated. See the g:option-context-set-translate-func and g:option-context-set-translation-domain functions.
Examples:
(setq context (g:option-context-new "A short description."))
=> #.(SB-SYS:INT-SAP #X561C3BDDC430)
(setf (g:option-context-summary context) "This is the summary.")
=> "This is the summary."
(g:option-context-help context nil)
=>
"Aufruf:
  sbcl [OPTION …] A short description.

This is the summary.

Hilfeoptionen: -h, --help Hilfeoptionen anzeigen "
See also:
2024-11-19
Function glib:option-context-description (context)
Syntax:
(g:option-context-description context) => description
(setf (g:option-context-descripton context) description)
Arguments:
context -- a g:option-context instance
description -- a string to be shown in --help output after the list of options, or nil
Details:
The g:option-context-description function returns the description. The (setf g:option-context-description) function adds a string to be displayed in --help output after the list of options. This text often includes a bug reporting address.

Note that the summary is translated. See the g:option-context-set-translate-func function.
Examples:
(setq context (g:option-context-new "A short description"))
=> #.(SB-SYS:INT-SAP #X55637A1CF6D0)
(setf (g:option-context-description context) "More descriptions.")
=> "More descriptions."
(g:option-context-help context nil)
"Aufruf:
  sbcl [OPTION …] A short description

Hilfeoptionen: -h, --help Hilfeoptionen anzeigen

More descriptions. "
See also:
2024-11-19
Callback glib:translate-func
Syntax:
lambda (str) => result
Arguments:
str -- a untranslated string
result -- a string with the translation for the current locale
Details:
The type of functions which are used to translate user visible strings, for --help output.
See also:
2024-11-19
Function glib:option-context-set-translate-func (context func)
Arguments:
context -- a g:option-context instance
func -- a g:translate-func callback function, or nil
Details:
Sets the function which is used to translate the user visible strings of the option context, for --help output. If the func argument is nil, strings are not translated.

Note that option groups have their own translation functions, this function only affects the parameter argument of the g:option-context-new function, the summary argument of the g:option-context-summary function, and the description argument of the g:option-context-description function.

If you are using GNU gettext, you only need to set the translation domain, see the g:option-context-set-translation-domain function.
See also:
2024-11-19
Function glib:option-context-set-translation-domain (context domain)
Arguments:
context -- a g:option-context instance
domain -- a string with the translation domain to use
Details:
A convenience function to use GNU gettext for translating user visible strings.
See also:
#2024-11-19
Function glib:option-context-parse (context &rest argv)
Arguments:
context -- a g:option-context instance
argv -- a list of strings with the command line arguments
Returns:
True if the parsing was successful, false if an error occurred.
Details:
Parses the command line arguments, recognizing options which have been added to the option context. A side-effect of calling this function is that the g:prgname function will be called.

If the parsing is successful, any parsed arguments are removed from the list and argv is updated accordingly. A -- option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with -. In case of an error, argv is left unmodified.

If automatic --help support is enabled, see the g:option-context-help-enabled function, and the argv list contains one of the recognized help options, this function will produce help output to stdout and call exit(0).

Note that function depends on the current locale for automatic character set conversion of string and filename arguments.
See also:
#2024-11-19
Function glib:option-context-parse-strv (context arguments)
Arguments:
context -- a g:option-context instance
arguments -- a list of strings with the command line arguments, which must be in UTF-8 on Windows, starting with GLib 2.62, arguments can be nil, which matches the g:option-context-parse function
Returns:
True if the parsing was successful, false if an error occurred.
Details:
Parses the command line arguments. This function is similar to the g:option-context-parse function except that it respects the normal memory rules when dealing with a list of strings instead of assuming that the passed-in list are the command line arguments of the main function.

In particular, strings that are removed from the arguments list will be freed using the g_free() function.

On Windows, the strings are expected to be in UTF-8. This is in contrast to the g:option-context-parse function which expects them to be in the system codepage, which is how they are passed as the command line arguments to the main function. See the g_win32_get_command_line() function for a solution.

This function is useful if you are trying to use a g:option-context instance with a g:application instance.
See also:
#2024-11-19
Function glib:option-context-help-enabled (context)
Syntax:
(g:option-context-help-enabled context) => enabled
(setf (g:option-context-help-enabled context) enabled)
Arguments:
context -- a g:option-context instance
enabled -- true to enable --help output, false to disable it
Details:
Enables or disables automatic generation of --help output. By default, the g:option-context-parse function recognizes the options --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.
See also:
#2024-11-19
Function glib:option-context-ignore-unknown-options (context)
Syntax:
(g:option-context-ignore-unknown-options context) => ignore
(setf (g:option-context-ignore-unknown-options context) ignore)
Arguments:
context -- a g:option-context instance
ignore -- true to ignore unknown options, false to produce an error when unknown options are met
Details:
The g:option-context-ignore-unknown-options function returns whether unknown options are ignored or not. The (setf g:option-context-ignore-unknown-options) function sets whether to ignore unknown options or not. If an argument is ignored, it is left in the list of command line arguments after parsing. By default, the g:option-context-parse function treats unknown options as error.

This setting does not affect non-option arguments, that is, arguments that do not start with a dash. But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.
See also:
#2024-11-19
Function glib:option-context-help (context main &optional group)
Arguments:
context -- a g:option-context instance
main -- if true, only include the main group
group -- an optional g:option-group instance to create help for
Returns:
The newly allocated string containing the help text.
Details:
Returns a formatted, translated help text for the given option context. To obtain the text produced by the --help output, call
(g:option-context-help context t)  
To obtain the text produced by --help-all, call
(g:option-context-help context nil)  
To obtain the help text for an option group, call
(g:option-context-help context nil group)  
See also:
#2024-11-19
Function glib:option-context-strict-posix (context)
Arguments:
context -- a g:option-context instance
strict -- true if strict POSIX is enabled, false otherwise
Details:
The g:option-context-strict-posix function returns whether strict POSIX code is enabled. The (setf g:option-context-strict-posix) function sets strict POSIX mode. By default, this mode is disabled.

In strict POSIX mode, the first non-argument parameter encountered, for example, filename, terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed.

If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options.

As an example, consider ls foo -l. With GNU style parsing, this will list foo in long mode. In strict POSIX style, this will list the files named foo and -l.

It may be useful to force strict POSIX mode when creating "verb style" command line tools. For example, the gsettings command line tool supports the global option --schemadir as well as many subcommands, get, set, etc., which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand, which can be determined by examining the verb name, which should be present in the second command line argument after parsing.
See also:
#2024-11-19
Function glib:option-context-add-main-entries (context entries domain)
Arguments:
context -- a g:option-context instance
entries -- a list of option entries
domain -- a string with a translation domain to use for translating the --help output for the options in entries with GNU gettext, or nil
Details:
A convenience function which creates a main group if it does not exist, adds the option entries to it and sets the translation domain.

The list of option entries has the following syntax. See the g:option-context documentation for a complete example.
(let ((entries '((long-name
                  short-name
                  flags
                  arg
                  arg-data
                  description
                  arg-description)
                 (<next option>)
                 )))
   ...)  
long-name
The string with the long name of an option can be used to specify it in a command line as --long-name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long-name.
short-name
If an option has a short name, it can be specified -short-name in a command line. The argument short-name must be a printable ASCII character different from '-', or #Nul if the option has no short name.
flags
Flags from the g:option-flags bitfield.
arg
The type of the option, as a g:option-arg value.
arg-data
If the arg type is :callback, then arg-data must point to a GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, arg-data is a pointer to a location to store the value, the required type of the location depends on the arg type. If the arg type is :string or :filename the location will contain a newly allocated string if the option was given.
description
The string with the description for the option in --help output. The description is translated using the translate-func callback function of the group, see the g:option-group-set-translation-domain function.
arg-description
The string with the placeholder to use for the extra argument parsed by the option in --help output. The arg-description argument is translated using the translate-func callback function of the group, see the g:option-group-set-translation-domain function.
See also:
2024-11-19
Function glib:option-context-add-group (context group)
Arguments:
context -- a g:option-context instance
group -- a g:option-group instance to add
Details:
Adds a g:option-group instance to the option context, so that parsing with the option context will recognize the options in the group. Note that the group will be freed together with the option context when the g:option-context-free function is called, so you must not free the group yourself after adding it to an option context.
See also:
#2024-11-19
Function glib:option-context-main-group (context)
Syntax:
(g:option-context-main-group context) => group
(setf (g:option-context-main-group context) group)
Arguments:
context -- a g:option-context instance
group -- a g:option-group instance
Details:
The g:option-context-main-group function returns the main group of context. The (setf g:option-context-main-group) function sets a g:option-group instance as main group of the option context. This has the same effect as calling the g:option-context-add-group function, the only difference is that the options in the main group are treated differently when generating --help output.
See also:
2024-11-19
CStruct glib:option-group
Returned by:
Details:
The g:option-group structure defines the options in a single group. The structure has only private fields and should not be directly accessed.

All options in a group share the same translation function. Libraries which need to parse command line options are expected to provide a function for getting a g:option-group instance holding their options, which the application can then add to its g:option-context instance.
See also:
2024-11-19
Macro glib:with-option-group ((group &rest args) &body body)
Syntax:
(g:with-option-group (group name description help-description) body) => result
Arguments:
group -- a g:option-group instance to create and initialize
name -- a string with the name for the option group
description -- a string with a description for this option group to be shown in --help output
help-description -- a string with a description for the --help-name option
Details:
The g:with-option-group macro allocates a new g:option-group instance, initializes the option group with the given arguments and executes the body that uses the option group. After execution of the body the allocated memory for the option group is released. See the documentation of the g:option-group-new function for more information about the initialization of the new option group.
See also:
2024-11-19
Function glib:option-group-new (name description help-description)
Arguments:
name -- a string with the name for the option group, this is used to provide help for the options in this group with the --help-name option
description -- a string with a description for this group to be shown in --help output, this string is translated using the translation domain or translation function of the group
help-description -- a string with a description for the --help-name option, this string is translated using the translation domain or translation function of the group
Returns:
The newly created option group. It should be added to a g:option-context instance or freed with the g:option-group-unref function.
Details:
Creates a new g:option-group instance.
See also:
2024-11-19
Function glib:option-group-ref (group)
Arguments:
group -- a g:option-group instance
Returns:
The g:option-group instance.
Details:
Increments the reference count of group by one.
See also:
#2024-11-19
Function glib:option-group-unref (group)
Arguments:
group -- a g:option-group instance
Details:
Decrements the reference count of group by one. If the reference count drops to 0, the group will be freed and all memory allocated by the group is released.
See also:
#2024-11-19
Function glib:option-group-add-entries (group entries)
Arguments:
group -- a g:option-group instance
entries -- a list of option entries
Details:
Adds the options specified in entries to group. The list of option entries has the following syntax. See the g:option-context documentation for a complete example.
(let ((entries '((long-name
                  short-name
                  flags
                  arg
                  arg-data
                  description
                  arg-description)
                 (<next option>)
                 )))
   ...)  
long-name
The string with the long name of an option can be used to specify it in a command line as --long-name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long-name.
short-name
If an option has a short name, it can be specified -short-name in a command line. The argument short-name must be a printable ASCII character different from '-', or #Nul if the option has no short name.
flags
Flags from the g:option-flags bitfield.
arg
The type of the option, as a g:option-arg value.
arg-data
If the arg type is :callback, then arg-data must point to a GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, arg-data is a pointer to a location to store the value, the required type of the location depends on the arg type. If arg type is :string or :filename the location will contain a newly allocated string if the option was given.
description
The string with the description for the option in --help output. The description is translated using the translate-func of the group, see the g:option-group-set-translation-domain function.
arg-description
The string with the placeholder to use for the extra argument parsed by the option in --help output. The arg-description is translated using the translate-func of the group, see the g:option-group-set-translation-domain function.
See also:
2024-11-19
Function glib:option-group-set-translate-func (group func)
Arguments:
group -- a g:option-group instance
func -- a g:translate-func callback function
Details:
Sets the function which is used to translate user visible strings, for --help output. Different groups can use different g:translate-func functions. If the func argument is nil, strings are not translated.

If you are using GNU gettext, you only need to set the translation domain, see the g:option-group-set-translation-domain function.
See also:
2024-11-19
Function glib:option-group-set-translation-domain (group domain)
Arguments:
group -- a g:option-group instance
domain -- a string with the translation domain to use
Details:
A convenience function to use GNU gettext for translating user visible strings.
See also:
2024-11-19

Key-value file parser

Bitfield glib:key-file-flags
Declaration:
(cffi:defbitfield key-file-flags
  (:none 0)
  (:keep-comments #.(ash 1 0))
  (:keep-translations #.(ash 1 1)))  
Values:
:none
No flags, default behaviour.
:keep-coments
Use this flag if you plan to write the possibly modified contents of the key file back to a file. Otherwise all comments will be lost when the key file is written back.
:keep-translations
Use this flag if you plan to write the possibly modified contents of the key file back to a file. Otherwise only the translations for the current language will be written back.
Details:
Flags which influence the parsing of key values.
See also:
2025-1-12
CStruct glib:key-file
Details:
The g:key-file structure lets you parse, edit or create files containing groups of key-value pairs, which we call key files for lack of a better name. Several freedesktop.org specifications use key files now, for example, the Desktop Entry Specification and the Icon Theme Specification.

The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments.
# this is just an example
# there can be comments before the first group

[First Group]

Name=Key File Example this value shows escaping

# localized strings are stored in multiple key-value pairs Welcome=Hello Welcome[de]=Hallo Welcome[fr_FR]=Bonjour Welcome[it]=Ciao Welcome[be@latin]=Hello

[Another Group]

Numbers=2;20;-200;0 Booleans=true;false;true;true
Lines beginning with a '#' and blank lines are considered comments.

Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group.

Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form key[locale]=value, with a locale identifier of the form lang_COUNTRYMODIFIER where COUNTRY and MODIFIER are optional. Space before and after the '=' character are ignored. Newline, tab, carriage return and backslash characters in value are escaped as n, t, r, and \, respectively. To preserve leading spaces in values, these can also be escaped as s.

Key files can store strings, possibly with localized variants, integers, booleans and lists of these. Lists are separated by a separator character, typically ';' or ','. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash.

This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences:
  • .ini files use the ';' character to begin comments, key files use the '#' character.
  • Key files do not allow for ungrouped keys meaning only comments can precede the first group.
  • Key files are always encoded in UTF-8.
  • Key and Group names are case-sensitive. For example, a group called [GROUP] is a different from [group].
  • .ini files do not have a strongly typed boolean entry type, they only have GetProfileInt(). In key files, only true and false (in lower case) are allowed.
Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple times. The last entry wins. Key files may also contain multiple groups with the same name. They are merged together. Another difference is that keys and group names in key files are not restricted to ASCII characters.

This is a list of standard group and key names for key files.
"Desktop Entry"
The name of the main group of a desktop entry file, as defined in the Desktop Entry Specification. Consult the specification for more details about the meanings of the keys below.
"Type"
A key under "Desktop Entry", whose value is a string giving the type of the desktop entry. Usually "Application", "Link", or "Directory".
"Version"
A key under "Desktop Entry", whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file.
"Name"
A key under "Desktop Entry", whose value is a localized string giving the specific name of the desktop entry.
"GenericName"
A key under "Desktop Entry", whose value is a localized string giving the generic name of the desktop entry.
"NoDisplay"
A key under "Desktop Entry", whose value is a boolean stating whether the desktop entry should be shown in menus.
"Comment"
A key under "Desktop Entry", whose value is a localized string giving the tooltip for the desktop entry.
"Icon"
A key under "Desktop Entry", whose value is a localized string giving the name of the icon to be displayed for the desktop entry.
"Hidden"
A key under "Desktop Entry", whose value is a boolean stating whether the desktop entry has been deleted by the user.
"OnlyShowIn"
A key under "Desktop Entry", whose value is a list of strings identifying the environments that should display the desktop entry.
"NotShowIn"
A key under "Desktop Entry", whose value is a list of strings identifying the environments that should not display the desktop entry.
"TryExec"
A key under "Desktop Entry", whose value is a string giving the file name of a binary on disk used to determine if the program is actually installed. It is only valid for desktop entries with the Application type.
"Exec"
A key under "Desktop Entry", whose value is a string giving the command line to execute. It is only valid for desktop entries with the Application type.
"Path"
A key under "Desktop Entry", whose value is a string containing the working directory to run the program in. It is only valid for desktop entries with the Application type.
"Terminal"
A key under "Desktop Entry", whose value is a boolean stating whether the program should be run in a terminal window. It is only valid for desktop entries with the Application type.
"MimeType"
A key under "Desktop Entry", whose value is a list of strings giving the MIME types supported by this desktop entry.
"Categories"
A key under "Desktop Entry", whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu.
"StartupNotify"
A key under "Desktop Entry", whose value is a boolean stating whether the application supports the Startup Notification Protocol Specification.
"StartupWMClass"
A key under "Desktop Entry", whose value is string identifying the WM class or name hint of a window that the application will create, which can be used to emulate Startup Notification with older applications.
"URL"
A key under "Desktop Entry", whose value is a string giving the URL to access. It is only valid for desktop entries with the Link type.
"Application"
The value of the "Type", key for desktop entries representing applications.
"Link"
The value of the "Type", key for desktop entries representing links to documents.
"Directory"
The value of the "Type", key for desktop entries representing directories.
Examples:
Here is an example of loading a key file and reading a value:
(g:with-key-file (keyfile)
  ;; Load the key file
  (unless (g:key-file-load-from-file keyfile "rtest-glib-key-file.ini" :none)
    (error "Error loading the key file: RTEST-GLIB-KEY-FILE.INI"))
  ;; Read a string from the key file
  (let ((value (g:key-file-string keyfile "First Group" "Welcome")))
    (unless value
      (setf value "default-value"))
    ... ))    
Here is an example of creating and saving a key file:
(g:with-key-file (keyfile)
  ;; Load existing key file
  (g:key-file-load-from-file keyfile "rtest-glib-key-file.ini" :none)
  ;; Add a string to the First Group
  (setf (g:key-file-string keyfile "First Group" "SomeKey") "New Value")
  ;; Save to a file
  (unless (g:key-file-save-to-file keyfile "rtest-glib-key-file-example.ini")
    (error "Error saving key file."))
  ;; Or save to data for use elsewhere
  (let ((data (g:key-file-to-data keyfile)))
    (unless data
      (error "Error saving key file."))
    ... ))    
See also:
2025-1-12
Macro glib:with-key-file ((keyfile) &body body)
Syntax:
(g:with-key-file (keyfile) body) => result
Arguments:
keyfile -- a newly allocated g:key-file instance
Details:
The g:with-key-file macro allocates a new g:key-file instance and executes the body that uses the key file. After execution of the body the allocated memory for the key file is released.
See also:
2025-1-12
Macro glib:with-key-file-from-file ((keyfile path &optional flags) &body body)
Syntax:
(g:with-key-file-from-file (keyfile path flags) body) => result
Arguments:
keyfile -- a newly allocated g:key-file instance
path -- a pathname or namestring for the path of a file to load
flags -- an optional g:key-file-flags value, the default value is :none
Details:
The g:with-key-file-from-file macro allocates a new g:key-file instance and executes the body that uses the key file. After execution of the body the allocated memory for the key file is released.
See also:
2025-1-12
Macro glib:with-key-file-from-data ((keyfile data &optional flags) &body body)
Syntax:
(g:with-key-file-from-data (keyfile data flags) body) => result
Arguments:
keyfile -- a newly allocated g:key-file instance
data -- a string for the key file loaded in memory
flags -- an optional g:key-file-flags value, the default value is :none
Details:
The g:with-key-file-from-data macro allocates a new g:key-file instance and executes the body that uses the key file. After execution of the body the allocated memory for the key file is released.
See also:
2025-1-12
Function glib:key-file-new ()
Returns:
The new empty g:key-file instance.
Details:
Creates a new empty g:key-file instance. Use the g:key-file-load-from-file, or g:key-file-load-from-data functions to read an existing key file.
See also:
2025-1-12
Function glib:key-file-free (keyfile)
Arguments:
keyfile -- a g:key-file instance
Details:
Clears all keys and groups from keyfile, and decreases the reference count by 1. If the reference count reaches zero, frees the key file and all its allocated memory.
See also:
2025-1-12
Function glib:key-file-ref (keyfile)
Arguments:
keyfile -- a g:key-file instance
Returns:
The same g:key-file instance.
Details:
Increases the reference count of keyfile.
See also:
2025-1-12
Function glib:key-file-unref (keyfile)
Arguments:
keyfile -- a g:key-file instance
Details:
Decreases the reference count of keyfile by 1. If the reference count reaches zero, frees the key file and all its allocated memory.
See also:
2025-1-12
Function glib:key-file-set-list-separator (keyfile separator)
Arguments:
keyfile -- a g:key-file instance
separator -- a char for the separator
Details:
Sets the character which is used to separate values in lists. Typically ';' or ',' are used as separators. The default list separator is ';'.
See also:
2025-1-12
Function glib:key-file-load-from-file (keyfile path flags)
Arguments:
keyfile -- a g:key-file instance
path -- a pathname or namestring for the path of a file to load
flags -- a g:key-file-flags value
Returns:
True if a key file could be loaded, false otherwise.
Details:
Loads a key file into a g:key-file instance. If the file could not be loaded then false is returned.
See also:
2025-1-12
Function glib:key-file-load-from-data (keyfile data flags)
Arguments:
keyfile -- a g:key-file instance
data -- a string for the key file loaded in memory
flags -- a g:key-file-flags value
Returns:
True if a key file could be loaded, otherwise false.
Details:
Loads a key file from memory into a g:key-file instance. If the data cannot be loaded then false is returned.
See also:
2025-1-12
Function glib:key-file-load-from-bytes (keyfile bytes flags)
Arguments:
keyfile -- a g:key-file instance
bytes -- a g:bytes instance
flags -- a g:key-file-flags value
Returns:
True if a key file could be loaded, otherwise false.
Details:
Loads a key file from the data in the g:bytes instance. If the data cannot be loaded then false is returned.
See also:
2025-1-12
Function glib:key-file-load-from-data-dirs (keyfile file flags)
Arguments:
keyfile -- a g:key-file instance
file -- a string for the relative path to a filename to open and parse
flags -- a g:key-file-flags value
Returns:
The string containing the full path of the file, or nil if the file could not be loaded.
Details:
This function looks for a key file named file in the paths returned from the g_get_user_data_dir() and g_get_system_data_dirs() functions, loads the file into keyfile and returns the full path of the file. If the file could not be loaded then nil is returned.
See also:
2025-1-12
Function glib:key-file-load-from-dirs (keyfile file dirs flags)
Arguments:
keyfile -- a g:key-file instance
file -- a string for the relative path to a filename to open and parse
dirs -- a list of strings for the directories to search
flags -- a g:key-file-flags value
Returns:
The string containing the full path of the file, or nil if the file could not be loaded.
Details:
This function looks for a key file named file in the paths specified in dirs, loads the file into keyfile and returns the full path of the file. If the file could not be loaded then nil is returned.
See also:
2025-1-12
Function glib:key-file-to-data (keyfile)
Syntax:
(g:key-file-to-data keyfile) => data, len
Arguments:
keyfile -- a g:key-file instance
data -- a string holding the contents of the key file
len -- an integer for the length of data
Details:
Outputs the key file as a string.
See also:
2025-1-12
Function glib:key-file-save-to-file (keyfile path)
Arguments:
keyfile -- a g:key-file instance
path -- a pathname or namestring for the file to write to
Returns:
True if successful, otherwise false.
Details:
Writes the contents of the key file to a file.
See also:
2025-1-12
Function glib:key-file-start-group (keyfile)
Arguments:
keyfile -- a g:key-file instance
Returns:
The string with the start group of the key file.
Details:
Returns the name of the start group of the key file.
See also:
2025-1-12
Function glib:key-file-groups (keyfile)
Arguments:
keyfile -- a g:key-file instance
Returns:
The list of strings with the groups.
Details:
Returns all groups in the key file loaded with keyfile.
See also:
2025-1-12
Function glib:key-file-keys (keyfile group)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
Returns:
The list of strings with the keys.
Details:
Returns all keys for the group name. In the event that the group name cannot be found, nil is returned.
See also:
2025-1-12
Function glib:key-file-has-group (keyfile group)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
Returns:
True if group is a part of keyfile, false otherwise.
Details:
Looks whether the key file has the group group.
See also:
2025-1-12
Function glib:key-file-has-key (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key name
Returns:
True if key is a part of group, false otherwise.
Details:
Looks whether the key file has the key key in the group group.
See also:
2025-1-12
Function glib:key-file-value (keyfile group key)
Syntax:
(g:key-file-value keyfile group key) => value
(setf (g:key-file-value keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with a key
value -- a string with the value
Details:
The g:key-file-value function returns the raw value associated with key under group. Use the g:key-file-string functon to retrieve an unescaped UTF-8 string. In the event the key or group name cannot be found, nil is returned.

The (setf g:key-file-value) function associates a new value with key under group. If key cannot be found then it is created. If group cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use the g:key-file-string function.
See also:
2025-1-12
Function glib:key-file-string (keyfile group key)
Syntax:
(g:key-file-string keyfile group key) => value
(setf (g:key-file-string keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
value -- a string with the value for key
Details:
The g:key-file-string function returns the string value associated with key under group. In the event the key or the group name cannot be found, nil is returned. The (setf g:key-file-string) function associates a new string value with key under group. If key or group cannot be found then they are created. Unlike the g:key-file-value function, this function handles characters that need escaping, such as newlines.
See also:
2025-1-12
Function glib:key-file-locale-string (keyfile group key locale)
Syntax:
(g:key-file-locale-string keyfile group key locale) => value
(setf (g:key-file-locale-string keyfile group key locale) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
locale -- a string for the identifier
value -- a string with the value for the specified key or nil if the key cannot be found
Details:
The g:key-file-locale-string function returns the value associated with key under group translated in the given locale if available. If locale is nil then the current locale is assumed.

The (setf g:key-file-locale-string) function associates a string value for key and locale under group. If the translation for key cannot be found then it is created.

If key cannot be found then nil is returned. If the value associated with key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.
See also:
2025-1-12
Function glib:key-file-locale-for-key (keyfile group key &optional locale)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
locale -- a string for the locale identifier
Returns:
The string with the locale from the file, or nil if the key was not found or the entry in the file was untranslated.
Details:
Returns the actual locale which the result of the g:key-file-locale-string or g:key-file-locale-string-list function came from.

If calling the g:key-file-locale-string or g:key-file-locale-string-list function with exactly the same keyfile, group, key and locale, the result of those functions will have originally been tagged with the locale that is the result of this function.
See also:
2025-1-12
Function glib:key-file-boolean (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
Returns:
The boolean with the value associated with the key, or nil if the key was not found or could not be parsed.
Details:
The g:key-file-boolean function returns the value associated with key under group as a boolean. The (setf g:key-file-boolean) function associates a new boolean value with key under group. If key cannot be found then it is created.

If key cannot be found then nil is returned. Likewise, if the value associated with key cannot be interpreted as a boolean then nil.
See also:
2025-1-12
Function glib:key-file-integer (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
Returns:
The integer with the value associated with the key as an integer, or 0 if the key was not found or could not be parsed.
Details:
The g:key-file-integer function returns the value associated with key under group as an integer. The (setf g:key-file-integer) function associates a new integer with key under group. If key cannot be found then it is created.

If key cannot be found then 0 is returned. Likewise, if the value associated with key cannot be interpreted as an integer then 0 is returned.
See also:
2025-1-12
Function glib:key-file-int64 (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
Returns:
The integer with the value associated with the key as an integer, or 0 if the key was not found or could not be parsed. This is similar to the g:key-file-integer function but can return 64-bit results without truncation.
Details:
The g:key-file-int64 function returns the value associated with key under group as an integer. The (setf g:key-file-int64) function associates a new integer with key under group. If key cannot be found then it is created.

If key cannot be found then 0 is returned. Likewise, if the value associated with key cannot be interpreted as an integer then 0 is returned.
See also:
2025-1-12
Function glib:key-file-uint64 (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
Returns:
The integer with the value associated with the key as an integer, or 0 if the key was not found or could not be parsed. This is similar to the g:key-file-integer function but can return 64-bit results without truncation.
Details:
The g:key-file-uint64 function returns the value associated with key under group as an integer. The (setf g:key-file-uint64) function associates a new integer with key under group. If key cannot be found then it is created.

If key cannot be found then 0 is returned. Likewise, if the value associated with key cannot be interpreted as an integer then 0 is returned.
See also:
2025-1-12
Function glib:key-file-double (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key
Returns:
The double float with the value associated with the key as a double float, or 0.0 if the key was not found or could not be parsed.
Details:
The g:key-file-double function returns the value associated with key under group as a double float. If group is nil, the start group is used.

The (setf g:key-file-double) function associates a new double float with key under group. If key cannot be found then it is created.

If key cannot be found then 0.0 is returned. Likewise, if the value associated with key cannot be interpreted as a double float then 0.0 is returned.
See also:
2025-1-12
Function glib:key-file-string-list (keyfile group key)
Syntax:
(g:key-file-string-list keyfile group key) => value
(setf (g:key-file-string-list keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
value -- a list of strings
Details:
The g:key-file-string-list function returns the values associated with key under group. In the event the key or the group name cannot be found, nil is returned. The (setf g:key-file-string-list) function associates a list of string values for key under group. If key or group cannot be found then they are created.
See also:
2025-1-12
Function glib:key-file-locale-string-list (keyfile group key &optional locale)
Syntax:
(g:key-file-locale-string-list keyfile group key locale) => value
(setf (g:key-file-locale-string-list keyfile group key locale) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
locale -- a string for the locale identifier
value -- a list of strings
Details:
The g:key-file-locale-string-list function returns the values associated with key under group translated in the given locale if available. If the locale argument is nil, the default, then the current locale is assumed.

The (setf g:key-file-locale-string-list) function associates a list of string values for key and locale under group. If the translation for key cannot be found then it is created.

If the locale argument is to be not nil, or if the current locale will change over the lifetime of the g:key-file instance, it must be loaded with the :keep-translations value for the g:key-file-flags flags in order to load strings for all locales.

If the key argument cannot be found then nil is returned. If the values associated with key cannot be interpreted or no suitable translations can be found then the untranslated values are returned.
See also:
2025-1-12
Function glib:key-file-boolean-list (keyfile group key)
Syntax:
(g:key-file-boolean-list keyfile group key) => value
(setf (g:key-file-boolean-list keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
value -- a list of boolean values
Returns:
The values associated with the key as a list of boolean values, or nil if the key was not found or could not be parsed.
Details:
The g:key-file-boolean-list function returns the values associated with key under group as boolean values. The (setf g:key-file-boolean-list) function associates a list of boolean values with key under group. If key cannot be found then it is created. If group is nil, the start group is used.

If key cannot be found then nil is returned. Likewise, if the values associated with key cannot be interpreted as booleans then nil is returned.
See also:
2025-1-12
Function glib:key-file-integer-list (keyfile group key)
Syntax:
(g:key-file-integer-list keyfile group key) => value
(setf (g:key-file-integer-list keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
value -- a list of integers
Returns:
The values associated with the key as a list of integers, or nil if the key was not found or could not be parsed.
Details:
The g:key-file-integer-list function returns the values associated with key under group as integers. The (setf g:key-file-integer-list) function associates a list of integer values with key under group. If key cannot be found then it is created. If group is nil, the start group is used.

If key cannot be found then nil is returned. Likewise, if the values associated with key cannot be interpreted as integers then nil is returned.
See also:
2025-1-12
Function glib:key-file-double-list (keyfile group key)
Syntax:
(g:key-file-double-list keyfile group key) => value
(setf (g:key-file-double-list keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key name
value -- a list of double floats
Returns:
The values associated with the key as a list of double floats, or nil if the key was not found or could not be parsed.
Details:
The g:key-file-double-list function returns the values associated with key under group as double floats. The (setf g:key-file-double-list) function associates a list of double float values with key under group. If key cannot be found then it is created. If group is nil, the start group is used.

If key cannot be found then nil is returned. Likewise, if the values associated with key cannot be interpreted as double floats then nil is returned.
See also:
2025-1-12
Function glib:key-file-comment (keyfile group key)
Syntax:
(g:key-file-comment keyfile group key) => value
(setf (g:key-file-comment keyfile group key) value)
Arguments:
keyfile -- a g:key-file instance
group -- a string with the group name
key -- a string with the key name
value -- a string with the comment
Details:
The g:key-file-comment retrieves a comment above key from group. If key is nil then the comment will be read from above group. If both key and group are nil, then the comment will be read from above the first group in the file.

The (setf g:key-file-comment) function places a comment above key from group. If key is nil then the comment will be written above group. If both key and group are nil, then the comment will be written above the first group in the file.
See also:
2025-1-12
Function glib:key-file-remove-group (keyfile group)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name to remove
Returns:
True if the group was removed, false otherwise.
Details:
Removes the specified group from the key file.
See also:
2025-1-12
Function glib:key-file-remove-key (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key name to remove
Returns:
True if the key was removed, false otherwise.
Details:
Removes the specified key from the key file.
See also:
2025-1-12
Function glib:key-file-remove-comment (keyfile group key)
Arguments:
keyfile -- a g:key-file instance
group -- a string for the group name
key -- a string for the key name to remove
Returns:
True if the comment was removed, false otherwise.
Details:
Removes a comment above key from group. If key is nil then the comment will be removed above group. If both key and group are nil, then the comment will be removed above the first group in the file.
See also:
2025-1-12

GVariantType

GBoxed glib:variant-type
Returned by:
Details:
The GVariant type system is based, in large part, on the D-Bus type system, with two major changes and some minor lifting of restrictions. The D-Bus specification, therefore, provides a significant amount of information that is useful when working with g:variant parameters.

The first major change with respect to the D-Bus type system is the introduction of maybe (or "nullable") types. Any type in the GVariant type system can be converted to a maybe type, in which case, "nothing" (or "null") becomes a valid value. Maybe types have been added by introducing the character "m" to type strings.

The second major change is that the GVariant type system supports the concept of "indefinite types" - types that are less specific than the normal types found in D-Bus. For example, it is possible to speak of "an array of any type" in the GVariant type system, where the D-Bus type system would require you to speak of "an array of integers" or "an array of strings". Indefinite types have been added by introducing the characters "*", "?" and "r" to type strings.

Finally, all arbitrary restrictions relating to the complexity of types are lifted along with the restriction that dictionary entries may only appear nested inside of arrays.

Just as in D-Bus, GVariant types are described with type strings. Subject to the differences mentioned above, these strings are of the same form as those found in D-Bus. Note, however: D-Bus always works in terms of messages and therefore individual type strings appear nowhere in its interface. Instead, "signatures" are a concatenation of the strings of the type of each argument in a message. The GVariant type system deals with single values directly so GVariant type strings always describe the type of exactly one value. This means that a D-Bus signature string is generally not a valid GVariant type string - except in the case that it is the signature of a message containing exactly one argument.

An indefinite type is similar in spirit to what may be called an abstract type in other type systems. No value can exist that has an indefinite type as its type, but values can exist that have types that are subtypes of indefinite types. That is to say, the g:variant-type function will never return an indefinite type, but calling the g:variant-is-of-type function with an indefinite type may return true. For example, you cannot have a value that represents "an array of no particular type", but you can have an "array of integers" which certainly matches the type of "an array of no particular type", since "array of integers" is a subtype of "array of no particular type".

This is similar to how instances of abstract classes may not directly exist in other type systems, but instances of their non-abstract subtypes may. For example, in GTK, no object that has the GtkWidget type can exist, since the GtkWidget class is an abstract class, but a GtkButton object can certainly be instantiated, and you would say that the GtkButton is a GtkWidget object, since the GtkButton class is a subclass of the GtkWidget class.

Two types may not be compared by value. Use the g:variant-type-equal or g:variant-type-is-subtype-of functions.

GVariant Type Strings
The GVariant type string can be any of the following:
  • any basic type string (listed below)
  • "v", "r" or "*"
  • one of the characters "a" or "m", followed by another type string
  • the character "(", followed by a concatenation of zero or more other type strings, followed by the character ")"
  • the character "{", followed by a basic type string (see below), followed by another type string, followed by the character "}"
A basic type string describes a basic type as per the g:variant-type-is-basic function and is always a single character in length. The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", "h", "d", "s", "o", "g" and "?".

The above definition is recursive to arbitrary depth. The "aaaaai" and "(ui(nq((y)))s)" type strings are both valid type strings, as is the "a(aa(ui)(qna{ya(yd)}))" type string.

The meaning of each of the characters is as follows:
b
The type string of a boolean value.
y
The type string of a byte.
n
The type string of a signed 16 bit integer.
q
The type string of an unsigned 16 bit integer.
i
The type string of a signed 32 bit integer.
u
The type string of an unsigned 32 bit integer.
x
The type string of a signed 64 bit integer.
t
The type string of an unsigned 64 bit integer.
h
The type string of a signed 32 bit value that, by convention, is used as an index into an array of file descriptors that are sent alongside a D-Bus message.
d
The type string of a double precision floating point value.
s
The type string of a string.
o
The type string of a string in the form of a D-Bus object path.
g
The type string of a string in the form of a D-Bus type signature.
?
The type string of an indefinite type that is a supertype of any of the basic types.
v
The type string of a container type that contain any other type of value.
a
Used as a prefix on another type string to mean an array of that type. The "ai" type string, for example, is the type of an array of 32 bit signed integers.
m
Used as a prefix on another type string to mean a "maybe", or "nullable", version of that type. The "ms" type string, for example, is the type of a value that maybe contains a string, or maybe contains nothing.
()
Used to enclose zero or more other concatenated type strings to create a tuple type. The "(is)" type string, for example, is the type of a pair of an integer and a string.
r
The type string of an indefinite type that is a supertype of any tuple type, regardless of the number of items.
{}
Used to enclose a basic type string concatenated with another type string to create a dictionary entry type, which usually appears inside of an array to form a dictionary. The "a{sd}" type string, for example, is the type of a dictionary that maps strings to double precision floating point values. The first type (the basic type) is the key type and the second type is the value type. The reason that the first type is restricted to being a basic type is so that it can easily be hashed.
*
The type string of the indefinite type that is a supertype of all types. Note that, as with all type strings, this character represents exactly one type. It cannot be used inside of tuples to mean "any number of items".
Any type string of a container that contains an indefinite type is, itself, an indefinite type. For example, the "a*" type string (corresponding to an array) is an indefinite type that is a supertype of every array type. The "(*s)" type string is a supertype of all tuples that contain exactly two items where the second item is a string.

The "a{?*}" type string is an indefinite type that is a supertype of all arrays containing dictionary entries where the key is any basic type and the value is any type at all. This is, by definition, a dictionary. Note that, due to the restriction that the key of a dictionary entry must be a basic type. The "{**}" type string is not a valid type string.

Two types may not be compared by value. Use the g:variant-type-equal or g:variant-type-is-subtype-of functions. May be copied using the g:variant-type-copy function. g:variant-type-copy
See also:
2024-11-20
Function glib:variant-type-new (string)
Arguments:
string -- a valid g:variant-type type string
Returns:
The new g:variant-type instance.
Details:
Creates a new variant type corresponding to the type string given by string. It is a programmer error to call this function with an invalid type string. Use the g:variant-type-string-is-valid function if you are unsure.
Examples:
;; A string variant type
(g:variant-type-new "s") => #<GLIB:VARIANT-TYPE {100FEBF233}>
;; An integer variant type
(g:variant-type-new "i") => #<GLIB:VARIANT-TYPE {100FEBF613}>    
See also:
2024-11-20
Function glib:variant-type-copy (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
The new g:variant-type instance.
Details:
Makes a copy of a variant type.
See also:
2024-11-20
Function glib:variant-type-string-is-valid (string)
Arguments:
string -- a g:variant-type type string
Returns:
True if string is exactly one valid type string.
Details:
Checks if string is a valid variant type string.
See also:
2024-11-20
Function glib:variant-type-dup-string (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
The corresponding variant type string.
Details:
Returns a newly allocated copy of the variant type string corresponding to vtype.
See also:
2024-11-20
Function glib:variant-type-is-definite (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is definite.
Details:
Determines if the given variant type is definite, that is not indefinite. A type is definite if its variant type string does not contain any indefinite type characters like "*", "?", or "r". A variant type may not have an indefinite type, so calling this function on the result of the g:variant-type-new function will always result in true being returned. Calling this function on an indefinite type like "a*", however, will result in false being returned.
See also:
2024-11-20
Function glib:variant-type-is-container (vtype)
Arguments:
type -- a g:variant-type instance
Returns:
True if vtype is a container type.
Details:
Determines if the given variant type is a container type. Container types are any array, maybe, tuple, or dictionary entry types plus the variant type. This function returns true for any indefinite type for which every definite subtype is a container, the "a*" type string, for example.
See also:
2024-11-20
Function glib:variant-type-is-basic (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is a basic type.
Details:
Determines if the given variant type is a basic type. Basic types are booleans, bytes, integers, doubles, strings, object paths and signatures. Only a basic variant type may be used as the key of a dictionary entry. This function returns false for all indefinite types except the "?" type string.
See also:
2024-11-20
Function glib:variant-type-is-maybe (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is a maybe type.
Details:
Determines if the given variant type is a maybe type. This is true if the type string for vtype starts with a "m" type string. This function returns true for any indefinite type for which every definite subtype is a maybe type, the "m*" type string, for example.
See also:
2024-11-20
Function glib:variant-type-is-array (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is an array type.
Details:
Determines if the given variant type is an array type. This is true if the variant type string for type starts with a "a" type string. This function returns true for any indefinite type for which every definite subtype is an array type, "a*" type string, for example.
See also:
2024-11-20
Function glib:variant-type-is-tuple (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is a tuple type.
Details:
Determines if the given variant type is a tuple type. This is true if the variant type string for type starts with a ( type string or if type is a r type string. This function returns true for any indefinite type for which every definite subtype is a tuple type, the "r" type string, for example.
See also:
2024-11-20
Function glib:variant-type-is-dict-entry (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is a dictionary entry type.
Details:
Determines if the given variant type is a dictionary entry type. This is true if the type string for type starts with a { type string. This function returns true for any indefinite type for which every definite subtype is a dictionary entry type, the "{?*}" type string, for example.
See also:
2024-11-20
Function glib:variant-type-is-variant (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
True if vtype is the variant type.
Details:
Determines if the given variant type is the variant type.
See also:
2024-11-20
Function glib:variant-type-hash (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
The unsigned integer with the hash value.
Details:
The has value of the given variant type. A valid g:variant-type instance must be provided.
See also:
2024-11-20
Function glib:variant-type-equal (vtype1 vtype2)
Arguments:
vtype1 -- a g:variant-type instance
vtype2 -- a g:variant-type instance
Returns:
True if vtype1 and vtype2 are exactly equal.
Details:
Compares two variant types for equality. Only returns true if the types are exactly equal. Even if one type is an indefinite type and the other is a subtype of it, false will be returned if they are not exactly equal. If you want to check for subtypes, use the g:variant-type-is-subtype-of function. For both arguments, a valid g:variant-type instance must be provided.
See also:
2024-11-20
Function glib:variant-type-is-subtype-of (vtype supertype)
Arguments:
vtype -- a g:variant-type instance
supertype -- a g:variant-type instance
Returns:
True if vtype is a subtype of supertype.
Details:
Checks if vtype is a subtype of supertype. This function returns true if vtype is a subtype of supertype. All types are considered to be subtypes of themselves. Aside from that, only indefinite types can have subtypes.
See also:
2024-11-20
Function glib:variant-type-new-maybe (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
The new maybe g:variant-type instance.
Details:
Constructs the variant type corresponding to a maybe instance containing vtype or nothing.
See also:
2024-11-20
Function glib:variant-type-new-array (vtype)
Arguments:
vtype -- a g:variant-type instance
Returns:
The new array g:variant-type instance.
Details:
Constructs the variant type corresponding to an array of elements of the vtype type.
See also:
2024-11-20
Function glib:variant-type-new-tuple (&rest items)
Arguments:
items -- g:variant-type instances, one for each item
Returns:
The new tuple g:variant-type instance.
Details:
Constructs a new tuple type, from items.
See also:
2025-2-2
Function glib:variant-type-new-dict-entry (key value)
Arguments:
key -- a basic g:variant-type instance
value -- a g:variant-type instance
Returns:
The new dictionary entry g:variant-type instance.
Details:
Constructs the variant type corresponding to a dictionary entry with a key of key type and a value of value type.
See also:
2024-11-20
Function glib:variant-type-element (vtype)
Arguments:
vtype -- an array or maybe g:variant-type instance
Returns:
The element type of vtype.
Details:
Determines the element type of an array or maybe type. This function may only be used with array or maybe types.
See also:
2024-11-20
Function glib:variant-type-n-items (vtype)
Arguments:
vtype -- a tuple or dictionary entry g:variant-type instance
Returns:
The number of items in vtype.
Details:
Determines the number of items contained in a tuple or dictionary entry vtype. This function may only be used with tuple or dictionary entry types, but must not be used with the generic r tuple type. In the case of a dictionary entry type, this function will always return 2.
See also:
2024-11-20
Function glib:variant-type-first (vtype)
Arguments:
vtype -- a tuple or dictionary entry g:variant-type instance
Returns:
The first item type of vtype.
Details:
Determines the first item type of a tuple or dictionary entry type. This function may only be used with tuple or dictionary entry types, but must not be used with the generic r tuple type. In the case of a dictionary entry type, this returns the type of the key. The nil value is returned in case of type being the "()" type string. This call, together with the g:variant-type-next function provides an iterator interface over tuple and dictionary entry types.
See also:
2024-11-20
Function glib:variant-type-next (vtype)
Arguments:
vtype -- a g:variant-type instance from a previous call
Returns:
The next g:variant-type instance after type, or nil.
Details:
Determines the next item type of a tuple or dictionary entry type. The vtype argument must be the result of a previous call to the g:variant-type-first or g:variant-type-next functions. If called on the key type of a dictionary entry then this call returns the value type. If called on the value type of a dictionary entry then this call returns nil. For tuples, nil is returned when vtype is the last item in a tuple.
See also:
2024-11-20
Function glib:variant-type-key (vtype)
Arguments:
vtype -- a dictionary entry g:variant-type instance
Returns:
The key type of the dictionary entry.
Details:
Determines the key type of a dictionary entry type. This function may only be used with a dictionary entry type. Other than the additional restriction, this call is equivalent to the g:variant-type-first function.
See also:
2024-11-20
Function glib:variant-type-value (vtype)
Arguments:
vtype -- a dictionary entry g:variant-type instance
Returns:
The value type of the dictionary entry.
Details:
Determines the value type of a dictionary entry type. This function may only be used with a dictionary entry type.
See also:
2024-11-20

GVariant

CEnum glib:variant-class
Declaration:
(cffi:defcenum variant-class
  (:boolean     #.(char-code #b))
  (:byte        #.(char-code #y))
  (:int16       #.(char-code #n))
  (:uint16      #.(char-code #q))
  (:int32       #.(char-code #i))
  (:uint32      #.(char-code #u))
  (:int64       #.(char-code #x))
  (:uint64      #.(char-code #t))
  (:handle      #.(char-code #h))
  (:double      #.(char-code #d))
  (:string      #.(char-code #s))
  (:object-path #.(char-code #o))
  (:signature   #.(char-code #g))
  (:variant     #.(char-code #v))
  (:maybe       #.(char-code #m))
  (:array       #.(char-code #a))
  (:tuple       #.(char-code #())
  (:dict-entry  #.(char-code #{)))  
Values:
:boolean
The instance is a boolean.
:byte
The variant is a byte.
:int16
The variant is a signed 16 bit integer.
:uint16
The variant is an unsigned 16 bitinteger.
:int32
The variant is a signed 32 bit integer.
:unit32
The variant is an unsigned 32 bit integer.
:int64
The variant is a signed 64 bit integer.
:uint64
The variant is an unsigned 64 bit integer.
:handle
The variant is a file handle index.
:double
The variant is a double precision floating point value.
:string
The variant is a normal string.
:object-path
The variant is a D-Bus object path string.
:signature
The variant is a D-Bus signature string.
:variant
The variant is a variant.
:maybe
The variant is a maybe-typed value.
:array
The variant is an array.
:tuple
The variant is a tuple.
:dict-entry
The variant is a dictionary entry.
Details:
The range of possible toplevel types of g:variant parameters.
See also:
2024-11-20
CStruct glib:variant
Details:
The g:variant structure is a variant datatype. It stores a value along with information about the type of that value. The range of possible values is determined by the type. The type system used by g:variant instances is the g:variant-type type.

g:variant instances always have a type and a value, which are given at construction time. The variant type and value of a g:variant instance can never change other than by the g:variant instance itself being destroyed. A g:variant instance cannot contain a pointer.

A g:variant instance is reference counted using the g:variant-ref and g:variant-unref functions. The g:variant instance also has floating reference counts, see the g:variant-ref-sink function.

The g:variant structure is completely threadsafe. A g:variant instance can be concurrently accessed in any way from any number of threads without problems.

The g:variant structure is heavily optimised for dealing with data in serialised form. It works particularly well with data located in memory mapped files. It can perform nearly all deserialisation operations in a small constant time, usually touching only a single memory page. Serialised g:variant data can also be sent over the network.

The g:variant structure is largely compatible with D-Bus. Almost all types of g:variant instances can be sent over D-Bus. See the g:variant-type documentation for exceptions. However, g:variant structures serialisation format is not the same as the serialisation format of a D-Bus message body: use GDBusMessage, in the GIO library, for those.

For space-efficiency, the g:variant serialisation format does not automatically include the variant's length, type or endianness, which must either be implied from context (such as knowledge that a particular file format always contains a little-endian "v" which occupies the whole length of the file) or supplied out-of-band (for instance, a length, type and/or endianness indicator could be placed at the beginning of a file, network message or network stream).

A g:variant instance size is limited mainly by any lower level operating system constraints, such as the number of bits in :size. For example, it is reasonable to have a 2 GB file mapped into memory with GMappedFile, and call the g_variant_new_from_data() function on it.

For convenience to C programmers, the g:variant values features powerful varargs-based value construction and destruction. This feature is designed to be embedded in other libraries.

There is a Python-inspired text language for describing g:variant parameters. The g:variant structure includes a printer for this language and a parser with type inferencing.
See also:
2025-2-3
Function glib:variant-ref (value)
Arguments:
value -- a g:variant instance
Returns:
The same g:variant instance.
Details:
Increases the reference count of value.
See also:
2024-11-20
Function glib:variant-unref (value)
Arguments:
value -- a g:variant instance
Details:
Decreases the reference count of value. When its reference count drops to 0, the memory used by the variant is freed.
See also:
2024-11-20
Function glib:variant-ref-sink (value)
Arguments:
value -- a g:variant instance
Returns:
The same g:variant instance.
Details:
The g:variant structure uses a floating reference count system. All functions with names starting with g:variant-new- return floating references.

Calling the g:variant-ref-sink function on a g:variant instance with a floating reference will convert the floating reference into a full reference. Calling the g:variant-ref-sink function on a non-floating g:variant instance results in an additional normal reference being added.

In other words, if value is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference. If value is not floating, then this call adds a new normal reference increasing the reference count by one.

All calls that result in a g:variant instance being inserted into a container will call the g:variant-ref-sink function on the instance. This means that if the value was just created (and has only its floating reference) then the container will assume sole ownership of the value at that point and the caller will not need to unreference it. This makes certain common styles of programming much easier while still maintaining normal refcounting semantics in situations where values are not floating.
See also:
2024-11-20
Function glib:variant-take-ref (value)
Arguments:
value -- a g:variant instance
Returns:
The same g:variant instance.
Details:
If value is floating, sink it. Otherwise, do nothing. Typically you want to use the g:variant-ref-sink function in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful.

The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a g:variant instance. We certainly want to allow the user the flexibility to return a non-floating reference from this callback for the case where the value that is being returned already exists.

At the same time, the style of the g:variant API makes it likely that for newly created g:variant instances, the user can be saved some typing if they are allowed to return a g:variant instance with a floating reference.

Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will alway receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference.

This function has an odd interaction when combined with the g:variant-ref-sink function running at the same time in another thread on the same g:variant instance. If the g:variant-ref-sink function runs first then the result will be that the floating reference is converted to a hard reference. If the g:variant-take-ref function runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation.
See also:
#2025-3-9
Function glib:variant-is-floating (value)
Arguments:
value -- a g:variant instance
Returns:
The boolean whether value is floating.
Details:
Checks whether value has a floating reference count. This function should only ever be used to assert that a given variant is or is not floating, or for debug purposes. To acquire a reference to a variant that might be floating, always use the g:variant-ref-sink or g:variant-take-ref functions.

See the g:variant-ref-sink function for more information about floating reference counts.
See also:
2024-11-20
Function glib:variant-type (value)
Arguments:
value -- a g:variant instance
Returns:
The g:variant-type instance.
Details:
Determines the variant type of value. The return value is valid for the lifetime of value.
See also:
2024-11-20
Function glib:variant-type-string (value)
Arguments:
value -- a g:variant instance
Returns:
The variant type string for the variant type of value.
Details:
Returns the variant type string of value.
Examples:
(g:variant-type-string (g:variant-new-double 10.0d0)) => "d"
(g:variant-type-string (g:variant-new-string "test")) => "s"    
See also:
2024-11-20
Function glib:variant-is-of-type (value vtype)
Arguments:
value -- a g:variant instance
vtype -- a g:variant-type instance
Returns:
True if the variant type of value matches vtype.
Details:
Checks if a value has a variant type matching the provided vtype.
See also:
2024-11-20
Function glib:variant-is-container (value)
Arguments:
value -- a g:variant instance
Returns:
True if value is a container.
Details:
Checks if value is a container.
See also:
2024-11-20
Function glib:variant-compare (value1 value2)
Arguments:
value1 -- a basic-typed g:variant instance
value2 -- a g:variant instance of the same type
Returns:
The integer with a negative value if a < b, zero if a = b, positive value if a > b.
Details:
Compares value1 and value2. The variant types of value1 and value2 are :pointer only to allow use of this function with GTree, GPtrArray, etc. They must each be a g:variant instance.

Comparison is only defined for basic types, that is booleans, numbers, strings. For booleans, false is less than true. Numbers are ordered in the usual way. Strings are in ASCII lexographical order.

It is a programmer error to attempt to compare container values or two values that have types that are not exactly equal. For example, you cannot compare a 32-bit signed integer with a 32-bit unsigned integer. Also note that this function is not particularly well-behaved when it comes to comparison of doubles. In particular, the handling of incomparable values, like NaN, is undefined.

If you only require an equality comparison, the g:variant-equal function is more general.
See also:
2024-11-20
Function glib:variant-classify (value)
Arguments:
value -- a g:variant instance
Returns:
The g:variant-class value of value.
Details:
Classifies value according to its toplevel type.
See also:
2024-11-20
Function glib:variant-new-boolean (value)
Arguments:
value -- a boolean value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the boolean value.
Examples:
(g:variant-new-boolean nil) => #.(SB-SYS:INT-SAP #X5602D1E4F100)
(g:variant-boolean *) => NIL
(g:variant-new-boolean t) => #.(SB-SYS:INT-SAP #X5602D1E4F160)
(g:variant-boolean *) => T    
See also:
2024-11-20
Function glib:variant-boolean (value)
Arguments:
value -- a g:variant instance with a boolean value
Returns:
The boolean values true or false.
Details:
Returns the boolean value of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "b" type string.
Examples:
(g:variant-boolean (g:variant-new-boolean nil)) => NIL
(g:variant-boolean (g:variant-new-boolean t)) => T    
See also:
2024-11-20
Function glib:variant-new-byte (value)
Arguments:
value -- a :uchar value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :uchar value.
See also:
2024-11-20
Function glib:variant-byte (value)
Arguments:
value -- a g:variant instance with a :uchar value
Returns:
The :uchar value.
Details:
Returns the :uchar value of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "y" type string.
See also:
#2024-11-20
Function glib:variant-new-int16 (value)
Arguments:
value -- a :int16 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :int16 value.
See also:
2024-11-20
Function glib:variant-int16 (value)
Arguments:
value -- a g:variant instance with a :int16 value
Returns:
The :int16 value.
Details:
Returns the 16-bit signed integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "n" type string.
See also:
#2024-11-20
Function glib:variant-new-uint16 (value)
Arguments:
value -- a :uint16 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :uint16 value.
See also:
2024-11-20
Function glib:variant-uint16 (value)
Arguments:
value -- a g:variant instance with a :uint16 value
Returns:
The :uint16 value.
Details:
Returns the 16-bit unsigned integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "q" type string.
See also:
#2024-11-20
Function glib:variant-new-int32 (value)
Arguments:
value -- a :int32 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :int32 value.
See also:
2024-11-20
Function glib:variant-int32 (value)
Arguments:
value -- a g:variant instance with a :int32 value
Returns:
The :int32 value.
Details:
Returns the 32-bit signed integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "i" type string.
See also:
2024-11-20
Function glib:variant-new-uint32 (value)
Arguments:
value -- a :uint32 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :uint32 value.
See also:
2024-11-20
Function glib:variant-uint32 (value)
Arguments:
value -- a g:variant instance with a :uint32 value
Returns:
The :uint32 value.
Details:
Returns the 32-bit unsigned integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "u" type string.
See also:
#2024-11-20
Function glib:variant-new-int64 (value)
Arguments:
value -- a :int64 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :int64 value.
See also:
2024-11-20
Function glib:variant-int64 (value)
Arguments:
value -- a g:variant instance with a :int64 value
Returns:
The :int64 value.
Details:
Returns the 64-bit signed integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "x" type string.
See also:
#2024-11-20
Function glib:variant-new-uint64 (value)
Arguments:
value -- a :uint64 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with the :uint64 value.
See also:
2024-11-20
Function glib:variant-uint64 (value)
Arguments:
value -- a g:variant instance with a :uint64 value
Returns:
The :uint64 value.
Details:
Returns the 64-bit unsigned integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "t" type string.
See also:
#2024-11-20
Function glib:variant-new-handle (value)
Arguments:
value -- a :int32 value
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a new g:variant instance with a handle. By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you are not interacting with D-Bus, you probably do not need them.
See also:
2024-11-20
Function glib:variant-handle (value)
Arguments:
value -- a g:variant instance with a handle
Returns:
The :int32 value.
Details:
Returns the 32-bit signed integer of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "h" type string.

By convention, handles are indexes into an array of file descriptors that are sent alongside a D-Bus message. If you are not interacting with D-Bus, you probably do not need them.
See also:
#2024-11-20
Function glib:variant-new-double (value)
Arguments:
value -- a double float
Returns:
The floating reference to a g:variant instance.
Details:
Creates a new g:variant instance with a double float.
See also:
2024-11-20
Function glib:variant-double (value)
Arguments:
value -- a g:variant instance for a double float
Returns:
The double float.
Details:
Returns the double precision floating point value of value. It is an error to call this function with a value of any type other than a g:variant-type type with the "d" type string.
See also:
#2024-11-20
Function glib:variant-new-string (value)
Arguments:
string -- a normal UTF-8 string
Returns:
The floating reference to a g:variant instance.
Details:
Creates a g:variant instance with a string value. The string must be valid UTF-8. Use the g:variant-string function to retrieve the string.
Examples:
(g:variant-new-string "This is a string.")
=> #.(SB-SYS:INT-SAP #X55EF04FDCE00)
(g:variant-string *) => "This is a string."    
See also:
2024-11-20
Function glib:variant-string (value)
Arguments:
value -- a g:variant instance with a string
Returns:
The constant string, UTF-8 encoded.
Details:
Returns the string value of value. This includes the g:variant-type types with the "s", "o", and "g" type strings. The string will always be UTF-8 encoded. It is an error to call this function with a value of any type other than those three. The return value remains valid as long as value exists. See the g:variant-new-string function for an example.
See also:
2024-11-20
Function glib:variant-new-object-path (path)
Arguments:
path -- a string with a D-Bus object path
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a g:variant instance with the D-Bus object path in string. The string argument must be a valid D-Bus object path. Use the g:variant-is-object-path function if you are not sure.
See also:
#2024-11-20
Function glib:variant-is-object-path (string)
Arguments:
string -- a string with a D-Bus object path
Returns:
True if string is a D-Bus object path.
Details:
Determines if a given string is a valid D-Bus object path. You should ensure that string is a valid D-Bus object path before passing it to the g:variant-new-object-path function.

A valid object path starts with '/' followed by zero or more sequences of characters separated by '/' characters. Each sequence must contain only the characters "[A-Z][a-z][0-9]_". No sequence (including the one following the final '/' character) may be empty.
See also:
#2024-11-20
Function glib:variant-new-signature (signature)
Arguments:
signature -- a string with a signature
Returns:
The floating reference to a new g:variant instance.
Details:
Creates a g:variant instance with a D-Bus type signature in string. The string argument must be a valid D-Bus type signature. Use the g:variant-is-signature function if you are not sure.
See also:
#2024-11-20
Function glib:variant-is-signature (string)
Arguments:
string -- a normal C nul-terminated string
Returns:
True if string is a D-Bus type signature.
Details:
Determines if a given string is a valid D-Bus type signature. You should ensure that a string is a valid D-Bus type signature before passing it to the g:variant-new-signature function.

D-Bus type signatures consist of zero or more definite g:variant-type strings in sequence.
See also:
#2024-11-20
Function glib:variant-new-variant (value)
Arguments:
value -- a g:variant instance
Returns:
The floating reference to a new g:variant instance.
Details:
The result is a g:variant instance representing a variant containing the original value. If child is a floating reference, see the g:variant-ref-sink function, the new instance takes ownership of child.
See also:
#2024-11-20
Function glib:variant-new-tuple (&rest items)
Arguments:
items -- g:variant instances with the items to make the tuple out of
Returns:
The new g:variant instance with the tuple.
Details:
Creates a new tuple g:variant instance out of the items. The type is determined from the types of items.
Examples:
(g:variant-new-tuple (g:variant-new-int16 10) (g:variant-new-int16 20))
=> #.(SB-SYS:INT-SAP #X6195B5F9ED70)
(g:variant-print *)
=> "(10, 20)"    
See also:
2025-2-2
Function glib:variant-equal (value1 value2)
Arguments:
value1 -- a g:variant instance
value2 -- a g:variant instance
Returns:
True if value and value are equal.
Details:
Checks if value and value have the same type and value.
See also:
#2024-11-20
Function glib:variant-print (value &optional annotate)
Arguments:
value -- a g:variant instance
annotate -- true if type information should be included in the output
Returns:
The string holding the result.
Details:
Pretty-prints value in the format understood by the g:variant-parse function. If the annotate argument is true, then type information is included in the output.
See also:
2024-11-20
GBoxed glib:variant-dict
Returned by:
Details:
The g:variant-dict structure is a mutable interface to g:variant dictionaries. It can be used for doing a sequence of dictionary lookups in an efficient way on an existing g:variant dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones. The g:variant-dict structure can only be used with a(sv) dictionaries.

You allocate a g:variant-dict instance with the g:variant-dict-new function. The g:variant-dict-end function is used to convert the g:variant-dict instance back into a g:variant dictionary type. This also implicitly frees all associated memory.
Examples:
Using a g:variant-dict instance:
(defun add-to-count (orig)
  (let* ((dict (g:variant-dict-new orig))
         (variant (g:variant-dict-lookup-value dict "count")))
    (when variant
      (let ((value (1+ (g:variant-int32 variant))))
        (g:variant-dict-insert-value dict "count" (g:variant-new-int32 value))
        (g:variant-dict-end dict)))))    
See also:
2024-11-20
Function glib:variant-dict-new (from-asv)
Arguments:
from-asv -- a g:variant instance with which to initialize the dictionary
Returns:
The newly created g:variant-dict instance.
Details:
Allocates and initialises a new g:variant-dict instance.
See also:
2024-11-20
Function glib:variant-dict-contains (dict key)
Arguments:
dict -- a g:variant-dict instance
key -- a string with the key to look up in the dictionary
Returns:
True if key is in the dictionary.
Details:
Checks if the key exists in the dictionary.
See also:
2024-11-20
Function glib:variant-dict-lookup-value (dict key &optional vtype)
Arguments:
dict -- a g:variant-dict instance
key -- a string with the key to look up in the dictionary
vtype -- a g:variant-type instance with the expected type
Details:
Looks up a value in a g:variant-dict instance. If key is not found in the dictionary, nil is returned.

The vtype string specifies what type of value is expected. If the value associated with key has a different type then nil is returned.

If the key is found and the value has the correct type, it is returned. If vtype was specified then any non-nil return value will have this type.
See also:
2024-11-20
Function glib:variant-dict-insert-value (dict key value)
Arguments:
dict -- a g:variant-dict instance
key -- a string with the key to insert a value for
value -- a g:variant instance with the value to insert
Details:
Inserts, or replaces, a key in a g:variant-dict instance.
See also:
2024-11-20
Function glib:variant-dict-remove (dict key)
Arguments:
dict -- a g:variant-dict instance
key -- a string with the key to remove
Returns:
True if the key was found and removed.
Details:
Removes a key and its associated value from a g:variant-dict instance.
See also:
2024-11-20
Function glib:variant-dict-end (dict)
Arguments:
dict -- a g:variant-dict instance
Returns:
The new g:variant instance.
Details:
Returns the current value of dict as a g:variant instance, clearing it in the process.

It is not permissible to use dict in any way after this call except for reference counting operations.
See also:
2024-11-20
Function glib:variant-parse (vtype text)
Arguments:
vtype -- a g:variant-type instance, or a valid type string
text -- a string containing a g:variant instance in text form
Returns:
The g:variant instance.
Details:
Parses a g:variant instance from a text representation. If vtype is non-nil then the value will be parsed to have that type. This may result in additional parse errors, in the case that the parsed value does not fit the variant type, but may also result in fewer errors, in the case that the variant type would have been ambiguous, such as with empty arrays.

In the event that the parsing is successful, the resulting g:variant instance is returned. In case of any error, nil will be returned.

Officially, the language understood by the parser is any string produced by the g:variant-print function.
Examples:
(g:variant-parse (g:variant-type-new "b") "true")
=> #.(SB-SYS:INT-SAP #X7F99C4012440)
(g:variant-print *) => "true"
(g:variant-parse "b" "false")
=> #.(SB-SYS:INT-SAP #X564C855E8690)
(g:variant-print *) => "false"
(g:variant-parse (g:variant-type-new "i") "100")
=> #.(SB-SYS:INT-SAP #X7F99C4012CF0)
(g:variant-print * nil) => "100"
(g:variant-parse "d" "100")
=> #.(SB-SYS:INT-SAP #X564C855F9900)
(g:variant-print *) => "100.0"    
See also:
2024-11-21

Package gobject

GObject provides the object system used for Pango and GTK. This is the API documentation of a Lisp binding to GObject.

Type Information

Introduction to type information

The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined objects and interface types.

For type creation and registration purposes, all types fall into one of two categories: static or dynamic. Static types are never loaded or unloaded at run-time as dynamic types may be. Static types are created with the function g_type_register_static() that gets type specific information passed in via a GTypeInfo structure. Dynamic types are created with the function g_type_register_dynamic() which takes a GTypePlugin structure instead. The remaining type information (the GTypeInfo structure) is retrieved during runtime through the GTypePlugin structure and the g_type_plugin_*() API. These registration functions are usually called only once from a function whose only purpose is to return the type identifier for a specific class. Once the type (or class or interface) is registered, it may be instantiated, inherited, or implemented depending on exactly what sort of type it is. There is also a third registration function for registering fundamental types called g_type_register_fundamental() which requires both a GTypeInfo structure and a GTypeFundamentalInfo structure but it is seldom used since most fundamental types are predefined rather than user-defined.

Type instance and class structures are limited to a total of 64 KiB, including all parent types. Similarly, type instances' private data (as created by the function g_type_class_add_private()) are limited to a total of 64 KiB. If a type instance needs a large static buffer, allocate it separately (typically by using a GArray or GPtrArray structure) and put a pointer to the buffer in the structure.

A final word about type names. Such an identifier needs to be at least three characters long. There is no upper length limit. The first character needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent characters can be letters, numbers or any of '-_+'.

Types and functions for type information

Type gobject:type-t
Superclasses:
common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
mangled-p
Whether the type designator is mangled with the G_SIGNAL_TYPE_STATIC_SCOPE flag.
Details:
The g:type-t type specifier represents the unique GType identifier of a registered type. The g:type-t type specifier is identified by its g:gtype representation, a string for the name, or a numeric identifier. Functions accept g:type-t type specifiers as a g:gtype instance, a string or an integer and return a g:gtype instance. Use the g:gtype function to create a g:gtype instance. You can get the name or the numeric identifier with the g:gtype-name and g:gtype-id functions.
Fundamental types:
The fundamental types known to GObject and the types of values that correspond to the CFFI interface und Common Lisp.
ID     NAME               CFFI type      Lisp type
------------------------------------------------------------
 4     "void"           :void            NULL
 8     "GInterface"     :pointer
12     "gchar"          :char
16     "guchar"         :uchar
20     "gboolean"       :boolean         boolean
24     "gint"           :int
28     "guint"          :uint
32     "glong"          :long
36     "gulong"         :ulong
40     "gint64"         :int64
44     "guint64"        :uint64
48     "GEnum"                           g:enum
52     "GFlags"                          g:flags
56     "gfloat"         :float           single-float
60     "gdouble"        :double          double-float
64     "gchararray"     :string
68     "gpointer"       :pointer
72     "GBoxed"         :pointer         g:boxed
76     "GParam"         :pointer         g:param
80     "GObject"        :pointer         g:object
84     "GVariant"       :pointer         g:variant    
Lisp symbols for types:
In the Lisp API, a Lisp symbol is registered for each GType. The g:symbol-for-gtype function gets this Lisp symbol.
Examples:
Create a g:gtype instance from a string or a numeric identifier.
(g:gtype "gdouble") => #<GTYPE :name "gdouble" :id 60>
(g:gtype 60) => #<GTYPE :name "gdouble" :id 60>    
Get the name and the numeric identifier from a g:gtype instance.
(glib:gtype-id (g:gtype "gdouble")) => 60
(glib:gtype-name (g:gtype "gdouble")) => "gdouble"    
Convert from foreign.
(cffi:convert-from-foreign 60 'g:type-t)
=> #<GTYPE :name "gdouble" :id 60>
(cffi:convert-from-foreign "gdouble" 'g:type-t)
=> #<GTYPE :name "gdouble" :id 60>
(cffi:convert-from-foreign (g:gtype "gdouble") 'g:type-t)
=> #<GTYPE :name "gdouble" :id 60>    
Convert to foreign.
(cffi:convert-to-foreign 60 'g:type-t) => 60
(cffi:convert-to-foreign "gdouble" 'g:type-t) => 60
(cffi:convert-to-foreign (g:gtype "gdouble") 'g:type-t) => 60    
Get the Lisp symbol for a GType:
(g:symbol-for-gtype "GApplication")
=> GIO:APPLICATION
=> T    
See also:
2024-12-8
Struct glib:gtype
Returned by:
Slot Access Functions:
Details:
The g:gtype structure represents the unique identifier of a registered foreign GType type on the Lisp side. In the C library a GType type is represented as an integer. The g:type-t type specifier automatically converts between the Lisp g:gtype representation and the C integer.
Examples:
Create a g:gtype instance from a GType name:
(g:gtype "GApplication")
=> #<GTYPE :name "GApplication" :id 94607290994400>
(g:gtype-name *) => "GApplication"
(g:gtype-id **) => 94607290994400    
See also:
2024-12-8
Function glib:gtype-name (instance)
Arguments:
instance -- a g:gtype instance
Returns:
The string with the name of the GType type.
Details:
Returns the name of the GType type. The instance argument must be a valid g:gtype instance.
Examples:
(g:gtype-name (g:gtype "gboolean")) => "gboolean"
(g:gtype-name (g:gtype "GObject")) => "GObject"
(g:gtype-name (g:gtype "GSimpleAction")) => "GSimpleAction"    
See also:
2024-12-8
Function glib:gtype-id (instance)
Arguments:
instance -- a g:gtype instance
Returns:
The integer for the unique identifier of the GType type.
Details:
Returns the unique identifier for the GType type. The function returns 0 for a nil value, representing an invalid GType type.
Examples:
(g:gtype-id (g:gtype "gboolean")) => 20
(g:gtype-id (g:gtype "GObject")) => 80
(g:gtype-id (g:gtype "GAction")) => 95376336284736
(g:gtype-id (g:gtype "GSimpleAction")) => 95376336285744
(g:gtype-id nil) => 0    
See also:
2024-12-8
Function glib:gtype (thing)
Arguments:
thing -- a string, an integer, or an g:gtype instance
Returns:
The g:gtype instance for thing.
Details:
Returns a g:gtype instance for thing. If the string or the integer does not represent a valid GType type the nil value is returned and a warning is printed.
Examples:
(g:gtype 20) => #<GTYPE :name "gboolean" :id 20>
(g:gtype "gboolean") => #<GTYPE :name "gboolean" :id 20>
(g:gtype (g:gtype 20)) => #<GTYPE :name "gboolean" :id 20>
(g:gtype "unknown")
=> WARNING: unknown is not known to the GType system
=> NIL    
See also:
2024-12-8
Function glib:symbol-for-gtype (name-or-gtype)
Arguments:
name-or-gtype -- a string or a g:gtype instance representing a valid GType type
Returns:
The Lisp symbol representing the GType type.
Details:
Returns the Lisp symbol for the given name-or-gtype argument.

The Lisp symbol is used with the make-instance method to create an instance for a GType type from the Lisp side.
Examples:
(g:symbol-for-gtype "GApplication")
=> GIO:APPLICATION
=> T
(g:symbol-for-gtype (g:gtype "GSimpleAction"))
=> GIO:SiMPLE-ACTION
=> T
(make-instance *)
=> #<GIO:SIMPLE-ACTION {1007481A53}>       
See also:
2024-12-8
CStruct gobject:type-class
Declaration:
(cffi:defcstruct type-class
  (:type type-t))  
Details:
An opaque structure used as the base of all classes.
See also:
2024-12-8
CStruct gobject:type-interface
Declaration:
(cffi:defcstruct type-interface
  (:type type-t)
  (:instance-type type-t))  
Details:
An opaque structure used as the base of all interface types.
See also:
2024-12-8
CStruct gobject:type-instance
Declaration:
(cffi:defcstruct type-instance
  (:class (:pointer (:struct type-class))))  
Details:
An opaque structure used as the base of all type instances.
See also:
2024-12-8
Function gobject:type-is-abstract (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is an abstract type.
Details:
Checks if gtype is an abstract type. An abstract type cannot be instantiated and is normally used as an abstract base class for derived classes.
Examples:
(g:type-is-abstract "GtkWidget") => T
(g:type-is-abstract "GtkButton") => NIL    
See also:
2024-12-8
Function gobject:type-is-derived (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a dervied type.
Details:
Checks if gtype is derived or in object oriented terminology inherited from another type. This holds true for all non-fundamental types.
Examples:
(g:type-is-derived "gboolean") => NIL
(g:type-is-derived "GObject") => NIL
(g:type-is-derived "GtkWidget") => T    
See also:
2024-12-8
Function gobject:type-is-fundamental (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a fundamental type.
Details:
Checks if gtype is a fundamental type.
Examples:
(g:type-is-fundamental "gboolean") => T
(g:type-is-fundamental "GObject") => T
(g:type-is-fundamental "GtkWidget") => NIL    
See also:
2024-12-8
Function gobject:type-is-value-type (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a value type.
Details:
Checks if gtype is a value type and can be used with the g:value-init function.
Examples:
(g:type-is-value-type "gint") => T
(g:type-is-value-type "GObject") => T
(g:type-is-value-type "GEnum") => NIL    
See also:
2024-12-8
Function gobject:type-is-classed (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a classed type.
Details:
Checks if gtype is a classed type.
See also:
2024-12-8
Function gobject:type-is-interface (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is an interface type.
Details:
Checks if gtype is an interface type. An interface type provides a pure API, the implementation of which is provided by another type, which is then said to conform to the interface. GLib interfaces are somewhat analogous to Java interfaces and C++ classes containing only pure virtual functions, with the difference that GType interfaces are not derivable.
Examples:
(g:type-is-interface "GAction") => T
(g:type-is-interface (g:gtype "GAction")) => T
(g:type-is-interface "GSimpleAction") => NIL    
See also:
2024-12-8
Function gobject:type-from-instance (instance)
Arguments:
instance -- a valid g:type-instance instance
Returns:
The g:type-t type ID of instance.
Details:
Gets the type identifier from a given instance.
Notes:
Signals an error if the instance argument is not a valid g:type-instance instance.
Examles:
(g:type-from-instance (make-instance 'g:simple-action))
=> #<GTYPE :name "GSimpleAction" :id 97556076810288>    
See also:
2025-1-4
Function gobject:type-from-class (class)
Arguments:
class -- a valid g:type-class instance
Returns:
The g:type-t type ID of class.
Details:
Gets the type identifier from a given class instance.
Examples:
(g:type-from-class (g:type-class-ref "GObject"))
=> #<GTYPE :name "GObject" :id 80>    
See also:
2025-1-4
Function gobject:type-from-interface (iface)
Arguments:
iface -- a valid g:type-interface instance
Returns:
The g:type-t type ID of iface.
Details:
Gets the type identifier from a given interface instance.
Examples:
(g:type-from-interface (g:type-default-interface-ref "GtkOrientable"))
=> #<GTYPE :name "GtkOrientable" :id 134920864>    
See also:
2025-1-4
Function gobject:type-instance-class (instance)
Arguments:
instance -- a g:type-instance instance
Returns:
The g:type-class instance of instance.
Details:
Get the class structure of a given instance. This function should only be used in type implementations.
Examples:
(g:type-instance-class (make-instance 'g:simple-action))
=> #.(SB-SYS:INT-SAP #X58BA0B4DF320)
(g:type-from-class *)
=> #<GTYPE :name "GSimpleAction" :id 97556076810288>    
See also:
2024-12-8
Function gobject:type-check-instance-type (instance gtype)
Arguments:
instance -- a g:type-instance instance
gtype -- a g:type-t type ID to be checked
Returns:
True on success.
Details:
Checks if instance is an instance of the type identified by gtype or derived. This function should only be used in type implementations.
Examples:
(g:type-check-instance-type (make-instance 'g:simple-action) "GObject")
=> T
(g:type-check-instance-type (make-instance 'g:simple-action) "gboolean")
=> NIL
(g:type-check-instance-type (make-instance 'g:simple-action) "GAction")
=> T    
See also:
2024-12-8
Function gobject:type-check-class-type (class gtype)
Arguments:
class -- a g:type-class instance
gtype -- a g:type-t type ID to be checked
Returns:
True on success.
Details:
Checks if class is a class structure of the type identified by gtype or derived. This function should only be used in type implementations.
Examples:
(g:type-check-class-type (g:type-class-ref "GtkButton") "GObject") => T
(g:type-check-class-type (g:type-class-ref "GtkButton") "GtkWindow") => NIL    
See also:
2024-12-8
Function gobject:type-name (gtype)
Arguments:
gtype -- a g:type-t type ID to return the type name for
Returns:
The string with the type name, or nil.
Details:
Get the unique name that is assigned to a type ID. Note that this function returns nil, when gtype is not known.
Examples:
(g:type-name 60) => "gdouble"
(g:type-name "gdouble") => "gdouble"
(g:type-name (g:gtype "gdouble")) => "gdouble"
(g:type-name "unknown")
=> WARNING: unknown is not known to the GType system
=> NIL    
See also:
2024-12-8
Function gobject:type-parent (gtype)
Arguments:
gtype -- a derived g:type-t type ID
Returns:
The parent g:type-t type ID of gtype.
Details:
Returns the direct parent type of the passed in gtype. If the passed in gtype has no parent, for example, is a fundamental type, nil is returned.
Examples:
(g:type-parent "GtkWindow") => #<GTYPE :name "GtkWidget" :id 94209734120944>
(g:type-parent "GApplication") => #<GTYPE :name "GObject" :id 80>
(g:type-parent "GtkActionable") => #<GTYPE :name "GInterface" :id 8>
(g:type-parent "GObject") => NIL
(g:type-parent "gdouble") => NIL    
See also:
2024-12-8
Function gobject:type-children (gtype)
Arguments:
gtype -- a g:type-t parent type ID
Returns:
The list of g:type-t child type IDs.
Details:
Returns a list of type IDs, listing the child types of gtype.
Examples:
(g:type-children "GtkButton")
=> (#<GTYPE :name "GtkToggleButton" :id 94069209378496>
    #<GTYPE :name "GtkLinkButton" :id 94069209378816>
    #<GTYPE :name "GtkLockButton" :id 94069209383872>)    
See also:
2024-12-8
Function gobject:type-depth (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
The unsigned integer with the depth of gtype.
Details:
Returns the length of the ancestry of the passed in gtype. This includes gtype itself, so that, for example, a fundamental type has depth 1.
Examples:
(g:type-depth "gdouble") => 1
(g:type-depth "GtkButton") => 4    
See also:
2024-12-8
Function gobject:type-next-base (leaf root)
Arguments:
leaf -- a g:type-t type ID descendant of root and the type to be returned
root -- a g:type-t type ID immediate parent of the returned type
Returns:
Immediate g:type-t child type ID of root and anchestor of leaf.
Details:
Given a leaf and a root which is contained in its anchestry, return the type that root is the immediate parent of. In other words, this function determines the type that is derived directly from root which is also a base class of leaf. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type.
Examples:
(g:type-next-base "GtkToggleButton" "GtkWidget")
=> #<GTYPE :name "GtkButton" :id 94607001843920>    
See also:
2024-12-8
Function gobject:type-is-a (gtype is-a-type)
Arguments:
gtype -- a g:type-t type ID to check anchestry for
is-a-type -- a g:type-t type ID with the possible anchestor of gtype or the interface that gtype could conform to
Returns:
True if the gtype argument is a is-a-type.
Details:
If the is-a-type argument is a derivable type, check whether the gtype argument is a descendant of is-a-type. If is-a-type is an interface, check whether gtype conforms to it.
Examples:
(g:type-is-a "gboolean" "gboolean") => T
(g:type-is-a "GBytes" "GBoxed") => T
(g:type-is-a "GApplicationFlags" "GFlags") => T
(g:type-is-a "GApplication" "GObject") => T
(g:type-is-a "GParamBoolean" "GParam") => T    
See also:
2024-12-8
Function gobject:type-class-ref (gtype)
Arguments:
gtype -- a g:type-t type ID of a classed type
Returns:
The pointer to the g:type-class instance for the given gtype.
Details:
Increments the reference count of the class instance belonging to gtype and returns the pointer to the class instance. This function will create the class instance if it does not exist already. Returns nil when gtype is not a valid type ID for a classed type.
Examples:
(g:type-class-ref "GApplication") => #.(SB-SYS:INT-SAP #X55FA5306FE40)
(g:type-from-class *) => #<GTYPE :name "GApplication" :id 94533623145984>
(g:type-class-ref "GAction") => NIL
(g:type-class-ref "gdouble") => NIL
(g:type-class-ref "unknown") => NIL    
See also:
2024-12-8
Function gobject:type-class-peek (gtype)
Arguments:
gtype -- a g:type-t type ID of a classed type
Returns:
The g:type-class instance for the given gtype type ID or nil if the class does not currently exist.
Details:
This function is essentially the same as the g:type-class-ref function, except that the classes reference count is not incremented. As a consequence, this function may return nil if the class of the type passed in does not currently exist (has not been referenced before).
Examples:
(g:type-class-peek "GSimpleAction") => #.(SB-SYS:INT-SAP #X55FA5306FE40)
(g:type-from-class *) => #<GTYPE :name "GSimpleAction" :id 94533623145984>
(g:type-class-peek "GAction") => NIL
(g:type-class-peek "gdouble") => NIL
(g:type-class-peek "unknown") => NIL    
See also:
2024-12-8
Function gobject:type-class-unref (class)
Arguments:
class -- a pointer to the g:type-class instance to unreference
Details:
Decrements the reference count of the class instance being passed in. Once the last reference count of a class has been released, classes may be finalized by the type system.
See also:
2024-12-8
Function gobject:type-class-peek-parent (class)
Arguments:
class -- a g:type-class instance to retrieve the parent class for
Returns:
The parent class of class.
Details:
This is a convenience function often needed in class initializers. It returns the class intance of the immediate parent type of the class passed in. Since derived classes hold a reference count on their parent classes as long as they are instantiated, the returned class will always exist. This function is essentially equivalent to:
(g:type-class-peek (g:type-parent class))  
See also:
#2025-3-27
Function gobject:type-interface-peek (class itype)
Arguments:
class -- a g:type-class instance
itype -- a g:type-t interface type ID which this class conforms to
Returns:
The g:type-interface instance of itype if implemented by class, nil otherwise.
Details:
Returns the interface structure of an interface to which the passed in class conforms.
Examples:
(g:type-interface-peek (g:type-class-ref "GtkBox") "GtkOrientable")
=> #.(SB-SYS:INT-SAP #X080C6858)
(g:type-from-interface *)
=> #S(GTYPE :NAME "GtkOrientable" :%ID 134887472)    
See also:
2024-12-8
Function gobject:type-default-interface-ref (gtype)
Arguments:
gtype -- a g:type-t interface type ID
Returns:
The pointer to the default vtable for the interface of type gtype, or nil if gtype is not an interface type.
Details:
Increments the reference count for the interface type, and returns the default interface vtable for the type. Call the g:type-default-interface-unref function when you are done using the interface.

If the interface type is not currently in use, then the default vtable for the type will be created and initalized by calling the base interface init and default vtable init functions for the type. Calling this function is useful when you want to make sure that signals and properties for an interface have been installed.
Examples:
(g:type-default-interface-ref "GAction") => #.(SB-SYS:INT-SAP #X55D446D53DE0)
(g:type-from-interface *) => #<GTYPE :name "GAction" :id 94370208235568>
(g:type-default-interface-ref "GSimpleAction") => NIL
(g:type-default-interface-ref "gdouble") => NIL
(g:type-default-interface-ref "unknown") => NIL    
See also:
2024-12-8
Function gobject:type-default-interface-peek (gtype)
Arguments:
gtype -- a g:type-t interface type ID
Returns:
The default vtable for the interface of type gtype, nil if the type is not currently in use or is not an interface type.
Details:
If the interface type gtype is currently in use, returns its default interface vtable.
See also:
2024-12-8
Function gobject:type-default-interface-unref (iface)
Arguments:
iface -- a pointer to the default vtable instance for an interface, as returned by the g:type-default-interface-ref function
Details:
Decrements the reference count for the type corresponding to the interface default vtable of iface. If the type is dynamic, then when no one is using the interface and all references have been released, the finalize function for the default vtable of the interface will be called.
See also:
2024-12-8
Function gobject:type-interfaces (gtype)
Arguments:
gtype -- a g:type-t type ID to list interface types for
Returns:
The list of g:type-t interface type IDs.
Details:
Returns a list of type IDs, listing the interface types that gtype conforms to.
Examples:
(g:type-interfaces "GtkButton")
=> (#<GTYPE :name "GtkAccessible" :id 94209734120256>
    #<GTYPE :name "GtkBuildable" :id 94209734088896>
    #<GTYPE :name "GtkConstraintTarget" :id 94209734121424>
    #<GTYPE :name "GtkActionable" :id 94209734120688>)    
See also:
2024-12-8
Function gobject:type-interface-prerequisites (itype)
Arguments:
itype -- a g:type-t interface type ID
Returns:
The list of g:type-t type IDs containing the prerequisites of itype.
Details:
Returns the prerequisites of an interfaces type.
Examples:
(g:type-interface-prerequisites "GtkOrientable")
=> (#<GTYPE :name "GObject" :id 80>)    
See also:
2024-12-8
Function gobject:type-qdata (gtype quark)
Syntax:
(g:type-qdata type quark) => data
(setf (g:type-qdata type quark) data)
Arguments:
gtype -- a g:type-t type ID
quark -- a g:quark-as-string ID to identify the data
data -- the data
Details:
The g:type-qdata function obtains data which has previously been attached to gtype with the (setf g:type-qdata) function.

Note that this does not take subtyping into account. Data attached to one type cannot be retrieved from a subtype.
Examples:
(setf (g:type-qdata "gboolean" "mydata") "a string") => "a string"
(g:type-qdata "gboolean" "mydata") => "a string"
(setf (g:type-qdata "gboolean" "mydata") '(a b c)) => (A B C)
(g:type-qdata "gboolean" "mydata") => (A B C)
(setf (g:type-qdata "gboolean" "mydata") nil) => NIL
(g:type-qdata "gboolean" "mydata") => NIL    
See also:
2023-12-8
Function gobject:type-fundamental (gtype)
Arguments:
gtype -- a valid g:type-t type ID
Returns:
The fundamental g:type-t type ID of the gtype argument.
Details:
The fundamental type which is the ancestor of the gtype argument. Fundamental types are types that serve as ultimate bases for the derived types, thus they are the roots of distinct inheritance hierarchies.
Examples:
(g:type-fundamental "GSimpleAction") => #<GTYPE :name "GObject" :id 80>
(g:type-fundamental "GAction") => #<GTYPE :name "GInterface" :id 8>
(g:type-fundamental "GBytes") => #<GTYPE :name "GBoxed" :id 72>    
See also:
2024-12-8
Function gobject:type-ensure (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
The gtype type ID, or nil.
Details:
Ensures that the indicated gtype has been registered with the type system, and its initializer method has been run. If the gtype argument is a string and gtype is not already registered, the type initializer is called. On success, the gtype type ID is returned, otherwise nil.
See also:
2024-8-12

Various types and functions

Introduction to enumeration and Flag Types

The GLib type system provides fundamental types for enumeration and flags types. Flags types are like enumerations, but allow their values to be combined by bitwise OR. A registered enumeration or flags type associates a name and a nickname with each allowed value. When an enumeration or flags type is registered with the GLib type system, it can be used as value type for object properties, using the g:param-spec-enum or g:param-spec-flags functions.

Types and functions for enumeration and flags types

CStruct gobject:enum-class
Declaration:
(cffi:defcstruct enum-class
  (:type-class (:pointer (:struct type-class)))
  (:minimum :int)
  (:maximum :int)
  (:n-values :uint)
  (:values (:pointer enum-value)))  
Values:
:type-class
The parent class.
:minimum
The smallest possible value.
:maximum
The largest possible value.
:n-values
The number of possible values.
:values
The array of g:enum-value instances describing the individual values.
Details:
The class of an enumeration type holds information about its possible values.
See also:
2024-6-9
CStruct gobject:enum-value
Declaration:
(cffi:defcstruct enum-value
  (:value :int)
  (:name (:string :free-from-foreign nil :free-to-foreign nil))
  (:nick (:string :free-from-foreign nil :free-to-foreign nil)))  
Values:
:value
The enum value.
:name
The name of the value.
:nick
The nickname of the value.
Details:
A structure which contains a single enum value, its name, and its nickname.
See also:
2024-6-9
Function gobject:type-is-enum (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a "GEnum" type.
Details:
Checks whether gtype is a "GEnum" type.
See also:
2024-6-9
CStruct gobject:flags-class
Declaration:
(cffi:defcstruct flags-class
  (:type-class (:pointer (:struct type-class)))
  (:mask :uint)
  (:n-values :uint)
  (:values (:pointer flags-value)))  
Values:
:type-class
The parent class.
:mask
The mask covering all possible values.
:n-values
The number of possible values.
:values
The array of g:flags-value instances describing the individual values.
Details:
The class of a flags type holds information about its possible values.
See also:
2024-6-9
CStruct gobject:flags-value
Declaration:
(cffi:defcstruct flags-value
  (:value :uint)
  (:name (:string :free-from-foreign nil :free-to-foreign nil))
  (:nick (:string :free-from-foreign nil :free-to-foreign nil)))  
Values:
:value
The flags value.
:name
The name of the value.
:nick
The nickname of the value.
Details:
A structure which contains a single flags value, its name, and its nickname.
See also:
2024-6-9
Function gobject:type-is-flags (gtype)
Arguments:
type -- a g:type-t type ID
Returns:
True if type is a "GFlags" type.
Details:
Checks whether type is a "GFlags" type.
See also:
2024-6-9

Introduction to boxed types

A mechanism to wrap opaque C structures registered by the type system

GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy and free them, beyond that they are treated as opaque chunks of memory.

Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-GObject based libraries. They allow arbitrary structures to be handled in a uniform way, allowing uniform copying (or referencing) and freeing (or unreferencing) of them, and uniform representation of the type of the contained structure. In turn, this allows any type which can be boxed to be set as the data in a GValue, which allows for polymorphic handling of a much wider range of data types, and hence usage of such types as GObject property values.

GBoxed is designed so that reference counted types can be boxed. Use the type’s ‘ref’ function as the GBoxedCopyFunc, and its ‘unref’ function as the GBoxedFreeFunc. For example, for GBytes, the GBoxedCopyFunc is g_bytes_ref(), and the GBoxedFreeFunc is g_bytes_unref().

Functions for boxed types

Function gobject:type-is-boxed (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
True if gtype is a "GBoxed" type.
Details:
Checks whether gtype is a "GBoxed" type.
See also:
2024-4-6

Generic Values

CStruct gobject:value
Details:
The g:value structure is a variable container that consists of a type identifier and a specific value of that type. The type identifier within a g:value instance determines the type of the associated value. To create an undefined g:value instance, simply create a zero-filled g:value instance. To initialize the g:value instance, use the g:value-init function. A g:value instance cannot be used until it is initialized.
Examples:
These examples demonstrate some of the features.
(defun example-gvalue ()
  ;; Declare two variables of type g:value
  (gobject:with-values (value1 value2)
    ;; Initialization, setting and reading a value of type g:value
    (g:value-set value1 "string" "gchararray")
    (format t "value1 = ~a~%" (g:value-get value1))
    (format t "gtype  = ~a~%" (g:value-type value1))
    (format t "name   = ~a~%~%" (g:value-type-name value1))

;; The same for the second value (g:value-init value2 "gchararray") (setf (g:value-get value2) "a second string") (format t "value2 = ~a~%" (g:value-get value2)) (format t "gtype = ~a~%" (g:value-type value2)) (format t "name = ~a~%~%" (g:value-type-name value2))

;; Reuse value1 for an integer (g:value-unset value1) (g:value-set value1 42 "gint" ) (format t "value1 = ~a~%" (g:value-get value1)) (format t "gtype = ~a~%" (g:value-type value1)) (format t "name = ~a~%~%" (g:value-type-name value1))

;; Some test functions (assert (g:value-holds value1 "gint")) (format t "value holds integer is ~a~%" (g:value-holds value1 "gint")) (format t "value is integer ~a~%~%" (g:type-is-value "gint"))))
See also:
2024-12-21
Macro gobject:with-value ((var &rest args) &body body)
Syntax:
(g:with-value (gvalue) body) => result
(g:with-value (gvalue gtype) body) => result
(g:with-value (gvalue gtype value) body) => result
Arguments:
gvalue -- a g:value instance to create and initialize
gtype -- an optional g:type-t type ID
value -- an optional value corresponding to gtype to set
Details:
The g:with-value macro allocates a new g:value instance, initializes it with the given values and executes the body that uses gvalue. After execution of the body the g:value-unset function is called on gvalue. This clears the current value in gvalue, unsets the type and releases all resources associated with gvalue.
Notes:
The gvalue parameter is initialized with the g:value-init function and unset with the g:value-unset function. The optional value ist set with the g:value-set function.
See also:
2024-12-21
Macro gobject:with-values (vars &body body)
Syntax:
(g:with-values (gvalue1 gvalue2 ... gvaluen) body) => result
Arguments:
gvalue1 ... gvaluen -- newly created g:value instances
body -- a body that uses the bindings gvalue1 ... gvaluen
Details:
The g:with-values macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each gvalue can be initialized with a type and a value using the syntax for the g:with-value macro.
See also:
2024-12-21
Function gobject:value-holds (gvalue gtype)
Arguments:
gvalue -- a g:value instance
gtype -- a g:type-t type ID
Returns:
True if gvalue holds a value of gtype type.
Details:
Checks if gvalue holds or contains a value of gtype type.
Examples:
(g:with-value (gvalue "gint")
  (g:value-holds gvalue "gint"))
=> T    
See also:
2024-12-21
Function gobject:value-type (gvalue)
Arguments:
gvalue -- a g:value instance
Returns:
The g:type-t type ID of gvalue.
Details:
Get the type identifier of gvalue.
Examples:
(g:with-value (gvalue "gint")
  (g:value-type gvalue))
=> #<GTYPE :name "gint" :id 24>    
See also:
2024-12-21
Function gobject:value-type-name (gvalue)
Arguments:
gvalue -- a g:value instance
Returns:
The type name of gvalue.
Details:
Gets the the type name of gvalue.
Examples:
(g:with-value (gvalue "gint")
  (g:value-type-name gvalue))
=> "gint"    
See also:
2024-12-21
Function gobject:type-is-value (gtype)
Arguments:
gtype -- a g:type-t type ID
Returns:
Whether gtype is suitable as a g:value instance type.
Details:
Checks whether the passed in gtype ID can be used for the g:value-init function.

This function is equivalent to the g:type-is-value-type function.
See also:
2024-12-21
Function gobject:value-init (gvalue &optional gtype)
Arguments:
gvalue -- an uninitialized g:value instance
gtype -- an optional g:type-t type ID the gvalue argument should hold values of, or the default nil value
Returns:
The g:value instance that has been passed in.
Details:
Sets gvalue to zero and initializes it with the gtype type. If the gtype argument is nil, the gvalue argument is set to zero but not initialized.
See also:
2024-12-21
Function gobject:value-copy (src dest)
Arguments:
src -- an initialized g:value instance
dest -- an initialized g:value instance of the same type as src
Details:
Copies the value of src into dest.
See also:
2024-12-21
Function gobject:value-reset (gvalue)
Arguments:
gvalue -- an initialized g:value instance
Returns:
The g:value instance that has been passed in.
Details:
Clears the current value in gvalue and resets it to the default value as if the value had just been initialized.
See also:
2024-12-21
Function gobject:value-unset (gvalue)
Arguments:
value -- an initialized g:value instance
Details:
Clears the current value in gvalue and "unsets" the type, this releases all resources associated with this gvalue instance. An unset value is the same as an uninitialized (zero-filled) g:value instance.
See also:
2024-12-21
Function gobject:value-get (gvalue &optional gtype)
Syntax:
(g:value-get gvalue) => value)
(setf (g:value-get gvalue) value)
Arguments:
gvalue -- an initialized g:value instance
value -- a value which corresponds to the type of gvalue
Details:
The g:value-get function parses the g:value instance and returns the corresponding Lisp value. The (setf g:value-get) function sets the value of an initialized g:value instance.

Use the g:value-set function for initialization and setting a g:value instance in one step.
Notes:
This function replaces the g_value_get_<type>() funcions of the C API.
See also:
2024-12-21
Function gobject:value-set (gvalue value gtype)
Arguments:
gvalue -- a g:value instance to initialize and to set
value -- a value to set as the value of the g:value instance
gtype -- a g:type-t type ID for the g:value instance
Details:
The g:value-set function initializes the g:value instance and sets the value. Unlike the (setf g:value-get) function, this function first intializies the g:value instance for a value of gtype type.
Notes:
This function replaces the g_value_set_<type>() functions of the C API.
See also:
2024-12-21
Function gobject:value-type-compatible (src dest)
Arguments:
src -- a g:type-t source type ID to be copied
dest -- a g:type-t destination type ID for copying
Returns:
True if the g:value-copy function is possible with src and dest.
Details:
Returns whether a g:value instance of type src can be copied into a g:value instance of type dest.
See also:
2024-12-21
Function gobject:strdup-value-contents (gvalue)
Arguments:
gvalue -- a g:value instance which contents are to be described
Returns:
The string with the contents of gvalue.
Details:
Return a string, which describes the contents of a g:value instance. The main purpose of this function is to describe g:value contents for debugging output, the way in which the contents are described may change between different GLib versions.
Examples:
(g:with-values ((value1 "gboolean" nil)
                (value2 "gint" 199)
                (value3 "gdouble" 2.0)
                (value4 "gchararray" "string"))
  (values (g:strdup-value-contents value1)
          (g:strdup-value-contents value2)
          (g:strdup-value-contents value3)
          (g:strdup-value-contents value4)))
=> "FALSE"
=> "199"
=> "2.000000"
=> ""string""    
See also:
2024-12-21

Parameters and Values

Introduction to parameters and values

Standard Parameter and Value Types

GValue provides an abstract container structure which can be copied, transformed and compared while holding a value of any (derived) type, which is registered as a GType with a GTypeValueTable in its GTypeInfo structure. Parameter specifications for most value types can be created as GParamSpec derived instances, to implement, for example, GObject properties which operate on GValue containers.

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. All other characters are replaced by a '-' during construction.

Functions for GParamSpec

Bitfield gobject:param-flags
Declaration:
(cffi:defbitfield param-flags
  (:readable #.(ash 1 0))
  (:writable #.(ash 1 1))
  (:construct #.(ash 1 2))
  (:construct-only #.(ash 1 3))
  (:lax-validation #.(ash 1 4))
  (:static-name #.(ash 1 5))
  (:static-nick #.(ash 1 6))
  (:static-blurb #.(ash 1 7))
  (:deprecated #.(ash 1 31)))  
Values:
:readable
The parameter is readable.
:writable
The parameter is writable.
:construct
The parameter will be set upon object construction.
:construct-only
The parameter will only be set upon object construction.
:lax-validation
Upon parameter conversion strict validation is not required.
:static-name
The string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter.
:static-nick
The string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter.
:static-blurb
The string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter.
:deprecated
The parameter is deprecated and will be removed in a future version.
Details:
Through the g:param-flags flag values, certain aspects of parameters can be configured.
See also:
2024-12-22
CStruct gobject:param-spec
Declaration:
(cffi:defcstruct param-spec
  (:type-instance (:pointer (:struct type-instance)))
  (:name (:string :free-from-foreign nil :free-to-foreign nil))
  (:flags param-flags)
  (:value-type type-t)
  (:owner-type type-t))  
Values:
:type-instance
The private g:type-instance portion.
:name
The name of this parameter, always an interned string.
:flags
The g:param-flags value for this parameter.
:value-type
The g:type-t type ID for the g:value instance for this parameter.
:owner-type
The g:type-t type ID that uses this parameter.
Details:
The g:param-spec structure is an object structure that encapsulates the metadata required to specify parameters, such as, for example g:object properties.

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. All other characters are replaced by a '-' during construction. The result of this replacement is called the canonical name of the parameter.
See also:
2024-12-22
Function gobject:type-is-param (gtype)
Arguments:
gtype -- a g:type-t type ID
Details:
Checks whether gtype is a "GParam" type.
See also:
2024-12-22
Function gobject:is-param-spec (pspec)
Arguments:
pspec -- a g:param-spec instance
Details:
Checks whether pspec is a valid g:param-spec instance of "GParam" type or derived.
See also:
2024-12-22
Function gobject:param-spec-type (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Details:
Retrieves the g:type-t type ID of pspec.
See also:
2024-12-22
Function gobject:param-spec-type-name (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Details:
Retrieves the g:type-t type ID name of pspec.
See also:
2024-12-22
Function gobject:param-spec-value-type (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Details:
Retrieves the g:type-t type ID to initialize a g:value instance for this parameter.
See also:
2024-12-22
Function gobject:param-spec-ref (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The g:param-spec instance that was passed into this function.
Details:
Increments the reference count of pspec.
See also:
2024-12-22
Function gobject:param-spec-unref (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Details:
Decrements the reference count of a pspec.
See also:
2024-12-22
Function gobject:param-spec-ref-sink (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The g:param-spec instance that was passed into this function
Details:
Convenience function to ref and sink a g:param-spec instance.
See also:
2024-12-22
Function gobject:param-spec-default-value (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The g:value instance with the default value.
Details:
Gets the default value of pspec as a g:value instance.
See also:
2024-12-22
Function gobject:param-value-set-default (pspec value)
Arguments:
pspec -- a valid g:param-spec instance
value -- a g:value instance of correct type for pspec
Details:
Sets value to its default value as specified in pspec.
See also:
2024-12-22
Function gobject:param-value-defaults (pspec value)
Arguments:
pspec -- a valid g:param-spec instance
value -- a g:value instance of correct type for pspec
Returns:
The boolean whether value contains the canonical default for pspec.
Details:
Checks whether value contains the default value as specified in pspec.
See also:
2024-12-22
Function gobject:param-value-validate (pspec value)
Arguments:
pspec -- a valid g:param-spec instance
value -- a g:value instance of correct type for pspec
Returns:
The boolean whether modifying value was necessary to ensure validity.
Details:
Ensures that the contents of value comply with the specifications set out by pspec.

For example, a g:param-spec-int instance might require that integers stored in value may not be smaller than -42 and not be greater than +42. If value contains an integer outside of this range, it is modified accordingly, so the resulting value will fit into the range -42 ... +42.
See also:
2024-12-22
Function gobject:param-spec-name (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The string with the name of pspec.
Details:
Gets the name of a g:param-spec instance.
Examples:
(mapcar #'g:param-spec-name
        (g:object-class-list-properties "GtkApplication"))
=> ("application-id" "flags" "resource-base-path" "is-registered"
    "is-remote" "inactivity-timeout" "action-group" "is-busy"
    "register-session" "screensaver-active" "menubar" "active-window")    
See also:
2024-12-22
Function gobject:param-spec-nick (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The string with the nickname of pspec.
Details:
Get the nickname of a g:param-spec instance.
See also:
2024-12-22
Function gobject:param-spec-blurb (pspec)
Arguments:
pspec -- a valid g:param-spec instance
Returns:
The string with the short description of pspec.
Details:
Gets the short description of a g:param-spec instance.
See also:
2024-12-22
Function gobject:param-spec-internal (ptype name nick blurb flags)
Arguments:
ptype -- a g:type-t type ID for the property, must be derived from the "GParam" type
name -- a string with the canonical name of the property
nick -- a string with the nickname of the property
blurb -- a string with a short description of the property
flags -- a combination of flags from the g:param-flags bitfield
Returns:
The newly allocated g:param-spec instance.
Details:
Creates a new parameter specification instance. A property name consists of segments consisting of ASCII letters and digits, separated by either the '-' or '_' character. The first character of a property name must be a letter. Names which violate these rules lead to undefined behaviour.

When creating and looking up a g:param-spec instance, either separator can be used, but they cannot be mixed. Using '-' is considerably more efficient and in fact required when using property names as detail strings for signals.

Beyond name, g:param-spec instances have two more descriptive strings associated with them, nick, which should be suitable for use as a label for the property in a property editor, and blurb, which should be a somewhat longer description, suitable, for example, for a tooltip. The nick and blurb values should ideally be localized.
Examples:
(g:param-spec-internal "GParamBoolean"
                       "Boolean" "Bool" "Doku"
                       '(:readable :writable))
=> #.(SB-SYS:INT-SAP #X00933890)
(g:param-spec-type-name *)
=> "GParamBoolean"    
See also:
2024-12-22

Types and functions for parameters and values

CStruct gobject:param-spec-boolean
Declaration:
(cffi:defcstruct param-spec-boolean
  (:parent-instance (:pointer (:struct param-spec)))
  (:default-value :boolean))  
Values:
:parent-instance
The private g:param-spec portion.
:default-value
The boolean default value.
Details:
The g:param-spec derived structure that contains the meta data for boolean properties.
See also:
2024-9-13
Function gobject:param-spec-boolean (name nick blurb default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
default -- a boolean with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-boolean parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gboolean" type. See the g:param-spec-internal function for details on property names.
See also:
2024-9-13
Function gobject:value-boolean (gvalue)
Syntax:
(g:value-boolean gvalue) => value
(setf (g:value-boolan gvalue) value)
Arguments:
gvalue -- a g:value instance of "gboolean" type
value -- a boolean value
Details:
The g:value-boolean function gets the contents of a g:value instance of "gboolean" type. The (setf g:value-boolean) function sets the contents of the g:value instance to value.
See also:
2024-9-13
CStruct gobject:param-spec-char
Declaration:
(cffi:defcstruct param-spec-char
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :int8)
  (:maximum :int8)
  (:default-value :int8))  
Values:
:parent-instance
The private g:param-spec portion.
:minimum
The 8-bit integer with the minimum value.
:maximum
The 8-bit integer with the maximum value.
:default-value
The 8-bit integer with the default value.
Details:
The g:param-spec derived structure that contains the meta data for character properties.
See also:
2024-9-13
Function gobject:param-spec-char (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an 8-bit integer with the minimum value
maximum -- an 8-bit integer with the maximum value
default -- an 8-bit integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-char parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gchar" type. See the g:param-spec-internal function for details on property names.
See also:
2024-9-13
Function gobject:value-char (gvalue)
Syntax:
(g:value-char gvalue) => value
(setf (g:value-char gvalue) value)
Arguments:
gvalue -- a g:value instance of "gchar" type
value -- an 8-bit integer with the character value
Details:
The g:value-char function gets the contents of a g:value instance of "gchar" type. The (setf g:value-char) function sets the contents of a g:value instance to value.
Warning:
The g:value-char function has been deprecated since version 2.32 and should not be used in newly written code. The function return type is broken, see the g:value-schar function.
See also:
2024-9-13
Function gobject:value-schar (gvalue)
Syntax:
(g:value-schar gvalue) => value
(setf (g:value-schar gvalue) value)
Arguments:
gvalue -- a g:value instance of "gchar" type
value -- an integer with the character value
Details:
The g:value-schar function gets the contents of a g:value of "gchar" type. The (setf g:value-schar) function sets the contents of a g:value instance to value.
See also:
2024-9-13
CStruct gobject:param-spec-uchar
Declaration:
(cffi:defcstruct param-spec-uchar
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :uint8)
  (:maximum :uint8)
  (:default-value :uint8))  
Values:
:parent-instance
The private g:param-spec portion.
:minimum
The unsigned 8-bit integer with the minimum value.
:maximum
The unsigned 8-bit integer with the maximum value.
:default-value
The unsigned 8-bit integer with the default value.
Details:
The g:param-spec derived structure that contains the meta data for unsigned character properties.
See also:
2024-9-13
Function gobject:param-spec-uchar (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an unsigned 8-bit integer with the minimum value
maximum -- an unsigned 8-bit integer with the maximum value
default -- an unsigned 8-bit integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-uchar parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "guchar" type. See the g:param-spec-internal function for details on property names.
See also:
2024-9-13
Function gobject:value-uchar (gvalue)
Syntax:
(g:value-uchar gvalue) => value
(setf (g:value-uchar gvalue) value)
Arguments:
gvalue -- a g:value instance of "guchar" type
value -- an unsigned 8-bit integer with the unsigned character value
Details:
The g:value-uchar function gets the contents of a g:value instance of "guchar" type. The (setf g:value-uchar) function sets the contents of a g:value instance to value.
See also:
2024-9-13
CStruct gobject:param-spec-int
Declaration:
(cffi:defcstruct param-spec-int
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :int)
  (:maximum :int)
  (:default-value :int))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The integer with the minimum value.
:maximum
The integer with the maximum value.
:default-value
The integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for integer properties.
See also:
2024-12-22
Function gobject:param-spec-int (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an integer with the minimum value
maximum -- an integer with the maximum value
default -- an integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-int parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gint" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-int (gvalue)
Syntax:
(g:value-int gvalue) => value
(setf (g:value-int gvalue) value)
Arguments:
gvalue -- a g:value instance of "gint" type
value -- an integer
Details:
Integer contents of gvalue. The g:value-int function gets the contents of a g:value instance of "gint" type. The (setf value-int) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-uint
Declaration:
(cffi:defcstruct param-spec-uint
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :uint)
  (:maximum :uint)
  (:default-value :uint))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The unsigned integer with the minimum value.
:maximum
The unsigned integer with the maximum value.
:default-value
The unsigned integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for unsigned integer properties.
See also:
2024-12-22
Function gobject:param-spec-uint (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an unsigned integer with the minimum value
maximum -- an unsigned integer with the maximum value
default -- an unsigned integer with default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-uint parameter specification.
Details:
Creates a new parameter specificaton instance specifying a property of "guint" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-uint (gvalue)
Syntax:
(g:value-uint gvalue) => value
(setf (g:value-uint gvalue) value)
Arguments:
gvalue -- a g:value instance of "guint" type
value -- an unsigned integer
Details:
Unsigned integer contents of gvalue. The g:value-uint function gets the contents of a g:value instance of "guint" type. The (setf value-uint) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-long
Declaration:
(cffi:defcstruct param-spec-long
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :long)
  (:maximum :long)
  (:default-value :long))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The long integer with the minimum value.
:maximum
The long integer with the maximum value.
:default-value
The long integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for long integer properties.
See also:
2024-12-22
Function gobject:param-spec-long (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- a long integer with the minimum value
maximum -- a long integer with the maximum value
default -- a long integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-long parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "glong" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-long (gvalue)
Syntax:
(g:value-long gvalue) => value
(setf (g:value-long gvalue) value)
Arguments:
gvalue -- a g:value instance of "glong" type
value -- a long integer
Details:
Long integer contents of gvalue. The g:value-long function gets the contents of a g:value instance of "glong" type. The (setf value-long) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-ulong
Declaration:
(cffi:defcstruct param-spec-ulong
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :ulong)
  (:maximum :ulong)
  (:default-value :ulong))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The unsigned long integer with the minimum value.
:maximum
The unsigned long integer with the maximum value.
:default-value
The unsigned long integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for unsigned long integer properties.
See also:
2024-12-22
Function gobject:param-spec-ulong (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an unsigned long integer with the minimum value
maximum -- an unsigned long integer with the maximum value
default -- an unsigned long integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-ulong parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gulong" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-ulong (gvalue)
Syntax:
(g:value-ulong gvalue) => value
(setf (g:value-ulong gvalue) value)
Arguments:
gvalue -- a g:value instance of "gulong" type
value -- an unsigned long integer
Details:
Unsigned long integer contents of gvalue. The g:value-ulong function gets the contents of a g:value instance of "gulong" type. The (setf g:value-ulong) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-int64
Declaration:
(cffi:defcstruct param-spec-int64
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :int64)
  (:maximum :int64)
  (:default-value :int64))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The 64-bit integer with the value.
:maximum
The 64-bit integer with the maximum value.
:default-value
The 64-bit integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for 64 bit integer properties.
See also:
2024-12-22
Function gobject:param-spec-int64 (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- a 64-bit integer with the minimum value
maximum -- a 64-bit integer with the maximum value
default -- a 64-bit- integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-int64 parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gint64" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-int64 (gvalue)
Syntax:
(g:value-int64 gvalue) => value
(setf (g:value-int64 gvalue) value)
Arguments:
gvalue -- a g:value instance of "gint64" type
value -- a 64-bit integer
Details:
The 64-bit integer contents of gvalue. The g:value-int64 function gets the contents of a g:value instance of "gint64" type. The (setf g:value-int64) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-uint64
Declaration:
(cffi:defcstruct param-spec-uint64
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :uint64)
  (:maximum :uint64)
  (:default-value :uint64))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The unsigned 64-bit integer with the minimum value.
:maximum
The unsigned 64-bit integer with the maximum value.
:default-value
The unsigned 64-bit integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for unsigned 64 bit integer properties.
See also:
2024-12-22
Function gobject:param-spec-uint64 (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- an unsigned 64-bit integer with the minimum value
maximum -- an unsigned 64-bit integer with the maximum value
default -- an unsigned 64-bit integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-uint64 parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "guint64" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-uint64 (gvalue)
Syntax:
(g:value-uint64 gvalue) => value
(setf (g:value-uint64 gvalue) value)
Arguments:
gvalue -- a g:value instance of "guint64" type
value -- an unsigned 64-bit integer
Details:
Unsigned 64-bit integer contents of gvalue. The g:value-uint64 function gets the contents of a g:value instance of "guint64" type. The (setf g:value-uint64) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-float
Declaration:
(cffi:defcstruct param-spec-float
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :float)
  (:maximum :float)
  (:default-value :float)
  (:epsilon :float))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The single float for the minimum value.
:maximum
The single float for the maximum value.
:default-value
The single float for the default value.
:epsilon
The single float, values closer than epsilon will be considered identical, the default value is 1e-30.
Details:
A g:param-spec derived structure that contains the meta data for float properties.
See also:
2024-12-22
Function gobject:param-spec-float (name nick blurb minimum maximum default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
minimum -- a float with the minimum value
maximum -- a float with the maximum value
default -- a float with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-float parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gfloat" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-float (gvalue)
Syntax:
(g:value-float gvalue) => value
(setf (g:value-float gvalue) value)
Arguments:
gvalue -- a g:value instance of "gfloat" type
value -- a single float
Details:
Float contents of gvalue. The g:value-float function gets the contents of a g:value instance of "gfloat" type. The (setf g:value-float) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-double
Declaration:
(cffi:defcstruct param-spec-double
  (:parent-instance (:pointer (:struct param-spec)))
  (:minimum :double)
  (:maximum :double)
  (:default-value :double)
  (:epsilon :double))  
Values:
:parent-instance
Private g:param-spec portion.
:minimum
The double float with the minimum value.
:maximum
The double float with the maximum value.
:default-value
The double float with the default value.
:epsilon
The double float, values closer than epsilon will be considered identical, the default value is 1e-90.
Details:
A g:param-spec derived structure that contains the meta data for double properties.
See also:
2024-12-12
Function gobject:param-spec-double (name nick blurb minimum maximum default flags)
Arguments:
name -- a string for the canonical name
nick -- a string for the nick name
blurb -- a string for the description
minimum -- a double float for the minimum value
maximum -- a double float for the maximum value
default -- a double float for the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-double parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gdouble" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-double (gvalue)
Syntax:
(g:value-double gvalue) => value
(setf (g:value-double gvalue) value)
Arguments:
gvalue -- a g:value instance of "gdouble" type
value -- a double float
Details:
Double float contents of gvalue. The g:value-double function gets the contents of a g:value instance of "gdouble" type. The (setf g:value-double) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-enum
Declaration:
(cffi:defcstruct param-spec-enum
  (:parent-instance (:pointer (:struct param-spec)))
  (:enum-class (:pointer enum-class))
  (:default-value :int))  
Values:
:parent-instance
Private g:param-spec portion.
:enum-class
The g:enum-class class instance for the enum.
:default-value
The integer with the default value.
Details:
A g:param-spec derived structure that contains the meta data for enum properties.
See also:
2024-12-22
Function gobject:param-spec-enum (name nick blurb gtype default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
gtype -- a g:type-t type ID derived from the "GEnum" type
default -- an integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-enum parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "GEnum" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-enum (gvalue)
Syntax:
(g:value-enum gvalue) => value
(setf (g:value-enum gvalue) value)
Arguments:
gvalue -- a g:value instance whose type is derived from "GEnum"
value -- an integer or keyword for the enumeration value
Details:
Enumeration value contents of gvalue. The g:value-enum function gets the contents of a g:value instance of type "GEnum". The (setf g:value-enum) function sets the contents.
Examples:
(gobject:with-value (gvalue "GEmblemOrigin")
  (setf (g:value-enum gvalue) :device)
  (g:value-enum gvalue))
=> :DEVICE    
See also:
2024-12-22
CStruct gobject:param-spec-flags
Values:
:parent-instance
Private g:param-spec portion.
:flags-class
The g:flags-class class instance for the flags.
:default-value
The unsigned integer with the default value.
Details:
(cffi:defcstruct param-spec-flags
  (:parent-instance (:pointer (:struct param-spec)))
  (:flags-class (:pointer flags-class))
  (:default-value :uint))  
A g:param-spec derived structure that contains the meta data for flags properties.
See also:
2024-12-22
Function gobject:param-spec-flags (name nick blurb gtype default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
gtype -- a g:type-t type ID derived from the "GFlags" type
default -- an unsigned integer with the default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-flags parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "GFlags" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-flags (gvalue)
Syntax:
(g:value-flags gvalue) => value
(setf (g:value-flags gvalue) value)
Arguments:
gvalue -- a g:value instance whose type is derived from "GFlags"
value -- a list with keywords or an unsigned integer with the flags value
Details:
Flags contents of gvalue. The g:value-flags function gets the contents of a g:value instance of type "GFlags". The (setf g:value-flags) function sets the contents.
Examples:
(gobject:with-value (gvalue "GApplicationFlags")
  (setf (g:value-flags gvalue) '(:handles-open :is-service))
  (g:value-flags gvalue))
=> (:IS-SERVICE :HANDLES-OPEN)    
See also:
2024-12-22
CStruct gobject:param-spec-string
Declaration:
(cffi:defcstruct param-spec-string
  (:parent-instance (:pointer (:struct param-spec)))
  (:default-value (:string :free-to-foreign nil :free-from-foreign nil))
  (:cset-first (:string :free-to-foreign nil :free-from-foreign nil))
  (:cset-nth (:string :free-to-foreign nil :free-from-foreign nil))
  (:substitutor :char)
  (:flags-for-null :uint))  
Values:
:parent-instance
Private g:param-spec portion.
:default-value
The string with the default value.
:cset-frist
The string containing the allowed values for the first byte.
:cset-nth
The string containing the allowed values for the subsequent bytes.
:substitutor
The character with the replacement byte for bytes which do not match :cset-first or cset-nth.
:flags-for-null
The unsigned integer whether to replace empty string by nil and nil strings by an empty string.
Details:
A g:param-spec derived structure that contains the meta data for string properties.
See also:
2024-12-22
Function gobject:param-spec-string (name nick blurb default flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
default -- a string with default value
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-string parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gchararray" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-string (gvalue)
Syntax:
(g:value-string gvalue) => value
(setf (g:value-string gvalue) value)
Arguments:
gvalue -- a g:value of "gchararray" type
value -- caller-owned string to be duplicated for the g:value
Details:
String content of gvalue. The g:value-string function gets the contents of a g:value instance of "gchararray" type. The (setf g:value-string) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-param
Declaration:
(cffi:defcstruct param-spec-param
  (:parent-instance (:pointer (:struct param-spec))))  
Values:
:parent-instance
Private g:param-spec portion.
Details:
A g:param-spec derived structure that contains the meta data for properties of "GParam" type.
See also:
2024-12-22
Function gobject:param-spec-param (name nick blurb gtype flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
gtype -- a g:type-t type ID derived from the "GParam" type
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-param parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "GParam" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-param (gvalue)
Syntax:
(g:value-param gvalue) => value
(setf (g:value-param gvalue) value)
Arguments:
gvalue -- a g:value instance whose type is derived from "GParam"
value -- a g:param-spec value
Details:
The g:param-spec content of gvalue. The g:value-param function gets the contents of a g:value instance of "GParam" type. The (setf g:value-param) function sets the contents of a g:value instance to value.
See also:
2024-12-22
CStruct gobject:param-spec-boxed
Declaration:
(cffi:defcstruct param-spec-boxed
  (:parent-instance (:pointer (:struct param-spec))))  
Values:
:parent-instance
Private g:param-spec portion.
Details:
A g:param-spec derived structure that contains the meta data for boxed properties.
See also:
2024-12-22
Function gobject:param-spec-boxed (name nick blurb gtype flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
gtype -- a "GBoxed" derived type of this property
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-boxed parameter specification.
Details:
Creates a new parameter specification instance specifying a property derived of "GBoxed" type. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-boxed (gvalue)
Syntax:
(g:value-boxed gvalue) => value
(setf (g:value-boxed gvalue) value)
Arguments:
gvalue -- a g:value instance of "GBoxed" type
value -- a boxed value
Details:
Boxed contents of gvalue. The g:value-boxed function gets the contents of a g:value instance derived of the "GBoxed" type. The (setf g:value-boxed) function sets the contents of a g:value instance to value.
See also:
2024-12-22
Function gobject:value-take-boxed (gvalue value)
Arguments:
gvalue -- a g:value instance of "GBoxed" type
value -- a value
Details:
Sets the contents of a g:value instance of "GBoxed" type to value. The function takes over the ownership of the callers reference to value. The caller does not have to unref it any more.
See also:
2024-12-22
CStruct gobject:param-spec-pointer
Declaration:
(cffi:defcstruct param-spec-pointer
  (:parent-instance (:pointer (:struct param-spec))))  
Values:
:parent-instance
Private g:param-spec portion.
Details:
A g:param-spec derived structure that contains the meta data for pointer properties.
See also:
#2024-12-22
Function gobject:param-spec-pointer (name nick blurb flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-pointer parameter specification.
Details:
Creates a new parameter specification instance specifying a property of "gpointer" type. See the g:param-spec-internal function for details on property names.
See also:
#2024-12-22
Function gobject:value-pointer (gvalue)
Syntax:
(g:value-pointer gvalue) => value
(setf (g:value-pointer gvalue) value)
Arguments:
gvalue -- a valid g:value instance of gpointer
value -- pointer value to be set
Details:
Pointer contents of gvalue. The g:value-pointer function gets the contents of a g:value instance of "gpointer" type. The (setf g:value-pointer) function sets the contents of a g:value instance to value.
See also:
#2024-12-22
CStruct gobject:param-spec-object
Declaration:
(cffi:defcstruct param-spec-object
  (:parent-instance (:pointer (:struct param-spec))))  
Values:
:parent-instance
Private g:param-spec portion
Details:
A g:param-spec derived structure that contains the meta data for object properties.
See also:
#2024-12-22
Function gobject:param-spec-object (name nick blurb gtype flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
gtype -- a "GObject" derived type of this property
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-object parameter specification.
Details:
Creates a new parameter specification instance specifying a property of a "GObject" dervived type. See the g:param-spec-internal function for details on property names.
See also:
#2024-12-22
Function gobject:value-object (gvalue)
Syntax:
(g:value-object gvalue) => value
(setf (g:value-object gvalue) value)
Arguments:
gvalue -- a valid g:value instance of "GObject" derived type
value -- object value of derived "GObject" type
Details:
Object contents of gvalue. The g:value-object function gets the contents of a g:value instance of a derived "GObject" type. The (setf g:value-object)) function sets the contents of a g:value instance to value.

The (setf g:value-object) function increases the reference count of value, the g:value instance holds a reference to value. If you do not wish to increase the reference count of the object, that is, you wish to pass your current reference to the g:value instance because you no longer need it, use the g:value-take-object function instead.

It is important that your g:value instance holds a reference to value, either its own, or one it has taken, to ensure that the object will not be destroyed while the g:value instance still exists).
See also:
#2024-12-22
CStruct gobject:param-spec-gtype
Declaration:
(cffi:defcstruct param-spec-gtype
  (:parent-instance (:pointer (:struct param-spec)))
  (:is-a-type type-t))  
Values:
:parent-instance
Private g:param-spec portion.
:is-a-type
The g:type-t type ID whose subtypes can occur as values.
Details:
A g:param-spec derived structure that contains the meta data for g:type-t type ID properties.
See also:
2024-12-22
Function gobject:param-spec-gtype (name nick blurb is-a-type flags)
Arguments:
name -- a string with the canonical name
nick -- a string with the nick name
blurb -- a string with the description
is-a-type -- a g:type-t type ID whose subtypes are allowed as values of the property (use the "void" type for any type)
flags -- a g:param-flags value
Returns:
The newly created g:param-spec-gtype parameter specification.
Details:
Creates a new parameter specification instance specifying a "GType" property. See the g:param-spec-internal function for details on property names.
See also:
2024-12-22
Function gobject:value-gtype (gvalue)
Syntax:
(g:value-gtype gvalue) => value
(setf (g:value-gtype gvalue) value)
Arguments:
gvalue -- a valid g:value instance of g:type-t type ID
value -- a g:type-t type ID value
Returns:
The g:type-t type ID stored in gvalue.
Details:
The g:value-gtype function gets the contents of a g:type-t type ID value. The (setf g:value-gtype) function sets the contents.
See also:
2024-12-22
Function gobject:value-variant (gvalue)
Syntax:
(g:value-variant gvalue) => value
(setf (g:value-variant gvalue) value)
Arguments:
gvalue -- a g:value instance of "GVariant" type
value -- a g:variant parameter
Details:
Variant contents of gvalue. The g:value-variant function gets the contents of a g:value instance of type "GVariant". The (setf g:value-variant) function sets the contents.
See also:
#2024-12-22

GObject

Class gobject:object
Superclasses:
common-lisp:standard-object, common-lisp:t
Documented Subclasses:
gdk-pixbuf:pixbuf, gdk-pixbuf:pixbuf-animation, gdk-pixbuf:pixbuf-animation-iter, gdk-pixbuf:pixbuf-loader, gdk:cicp-params, gdk:clipboard, gdk:content-provider, gdk:cursor, gdk:device, gdk:device-tool, gdk:display, gdk:display-manager, gdk:dmabuf-texture-builder, gdk:drag, gdk:drag-surface, gdk:draw-context, gdk:drop, gdk:frame-clock, gdk:monitor, gdk:paintable, gdk:seat, gdk:snapshot, gdk:surface, gdk:toplevel, gio:action, gio:action-group, gio:action-map, gio:app-info, gio:app-launch-context, gio:application-command-line, gio:async-result, gio:cancellable, gio:file, gio:file-info, gio:icon, gio:list-model, gio:loadable-icon, gio:menu-attribute-iter, gio:menu-item, gio:menu-link-iter, gio:menu-model, gio:notification, gio:permission, gio:settings, gobject:binding, gobject:initially-unowned, gsk:renderer, gtk:accessible, gtk:actionable, gtk:alert-dialog, gtk:app-chooser, gtk:assistant-page, gtk:at-context, gtk:buildable, gtk:builder, gtk:builder-scope, gtk:cell-area-context, gtk:cell-editable, gtk:cell-layout, gtk:color-chooser, gtk:color-dialog, gtk:column-view-column, gtk:column-view-row, gtk:constraint, gtk:constraint-guide, gtk:constraint-target, gtk:editable, gtk:entry-buffer, gtk:event-controller, gtk:file-chooser, gtk:file-dialog, gtk:file-launcher, gtk:filter, gtk:font-chooser, gtk:font-dialog, gtk:icon-theme, gtk:im-context, gtk:layout-child, gtk:layout-manager, gtk:list-header, gtk:list-item, gtk:list-item-factory, gtk:native, gtk:native-dialog, gtk:notebook-page, gtk:orientable, gtk:page-setup, gtk:print-backend, gtk:print-context, gtk:print-dialog, gtk:print-job, gtk:print-operation-preview, gtk:print-settings, gtk:printer, gtk:recent-manager, gtk:root, gtk:scrollable, gtk:section-model, gtk:shortcut, gtk:shortcut-action, gtk:shortcut-manager, gtk:shortcut-trigger, gtk:sorter, gtk:string-object, gtk:style-context, gtk:style-provider, gtk:symbolic-paintable, gtk:text-buffer, gtk:text-child-anchor, gtk:text-mark, gtk:text-tag, gtk:tooltip, gtk:tree-drag-dest, gtk:tree-drag-source, gtk:tree-list-row, gtk:tree-model, gtk:tree-selection, gtk:tree-sortable, gtk:uri-launcher, gtk:window-group, pango:cairo-font, pango:cairo-font-map, pango:context, pango:coverage, pango:font, pango:font-face, pango:font-map, pango:fontset, pango:layout, pango:renderer
Direct Slots:
has-reference
Holds the true value when the instance is successfully registered.
pointer
Holds a foreign pointer to the C instance of a GObject.
Returned by:
Slot Access Functions:
Details:
The g:object class is the fundamental type providing the common attributes and methods for all object types in GTK, Pango and other libraries. The g:object class provides methods for object construction and destruction, property access methods, and signal support.
Lisp Implementation:
In the Lisp implementation two slots are added. The pointer slot holds the foreign pointer to the C instance of the object. The has-reference slot is initialized to the true value during creation of an object. See the slot access functions for examples.
Signal Details:
The "notify" signal
lambda (object pspec)    :no-hooks    
object
The g:object instance which received the signal.
pspec
The g:param-spec instance of the property which changed.
The signal is emitted on an object when one of its properties has been changed. Note that getting this signal does not guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value. This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g:signal-connect function call, like this:
(g:signal-connect switch "notify::active"
   (lambda (widget pspec)
     (declare (ignore pspec))
     (if (gtk:switch-active widget)
         (setf (gtk:label-label label) "The Switch is ON")
         (setf (gtk:label-label label) "The Switch is OFF"))))    
It is important to note that you must use canonical parameter names as detail strings for the notify signal.
See also:
2024-12-14
Accessor gobject:object-has-reference (object)
Syntax:
(g:object-has-reference object) => has-reference
Arguments:
object -- a g:object instance
has-reference -- true when registering object
Details:
Accessor of the has-reference slot of the g:object class. The slot is set to true when registering an object during creation.
See also:
2024-12-14
Accessor gobject:object-pointer (object)
Syntax:
(g:object-pointer object) => pointer
Arguments:
object -- a g:object instance
pointer -- a foreign pointer to the C instance of object
Details:
Accessor of the pointer slot of the g:object class. The g:object-pointer function gets the foreign C pointer of a g:object instance.
Examples:
(setq label (make-instance 'gtk:label)) => #<GTK:LABEL {E2DB181}>
(g:object-pointer label) => #.(SB-SYS:INT-SAP #X081BDAE0)    
See also:
2024-12-14
Function gobject:type-is-object (gtype)
Arguments:
gtype -- a g:type-t type ID to check
Returns:
False or true, indicating whether the gtype argument is a "GObject" type.
Details:
Checks if the passed in type ID is a "GObject" type or derived from it.
Examples:
(g:type-is-object "GtkLabel") => T
(g:type-is-object "GtkActionable") => NIL
(g:type-is-object "gboolean") => NIL
(g:type-is-object "unknown") => NIL
(g:type-is-object nil) => NIL    
See also:
2024-12-14
Function gobject:is-object (object)
Arguments:
object -- a valid g:type-instance instance to check
Details:
Checks whether the object argument is of "GObject" type or derived from it.
Examples:
(g:is-object (make-instance 'gtk-button)) => T    
See also:
2024-12-14
Function gobject:object-class-find-property (gtype name)
Arguments:
gtype -- a g:type-t type ID for an object class type
name -- a string with the name of the property to look up
Returns:
The g:param-spec instance for the property, or nil if the object class does not have a property of that name.
Details:
Looks up the g:param-spec instance for a property of an object class type. Signals an error if the gtype type ID is not a "GObject" type.
Examples:
Get the g:param-spec instance for the name property of the g:simple-action object.
(setq pspec (g:object-class-find-property "GSimpleAction" "name"))
=> #.(SB-SYS:INT-SAP #X560E17A46220)
(g:param-spec-name pspec) => "name"
(g:param-spec-type pspec) => #<GTYPE :name "GParamString" :id 94618525293072>
(g:param-spec-value-type pspec) => #<GTYPE :name "gchararray" :id 64>    
See also:
2024-12-14
Function gobject:object-class-list-properties (gtype)
Arguments:
gtype -- a g:type-t type ID of an object class
Returns:
The list of g:param-spec instances.
Details:
Gets a list of g:param-spec instances for all properties of an object class type. Signals an error if the gtype type ID is not a "GObject" type.
Examples:
(mapcar #'g:param-spec-name
        (g:object-class-list-properties "GApplication"))
=> ("application-id" "flags" "resource-base-path" "is-registered"
    "is-remote" "inactivity-timeout" "action-group" "is-busy")    
See also:
2024-12-14
Function gobject:object-interface-find-property (gtype name)
Arguments:
gtype -- a g:type-t type ID for an interface type
name -- a string with the name of a property to lookup
Returns:
The g:param-spec instance for the property of the interface type with, or nil if no such property exists.
Details:
Find the g:param-spec instance with the given property name for an interface type. Signals an error if the gtype type ID is not an "GInterface" type.
Examples:
(g:object-interface-find-property "GAction" "name")
=> #.(SB-SYS:INT-SAP #X55A6D24988C0)
(g:param-spec-name *)
=> "name"
(g:object-interface-find-property "GAction" "unknown")
=> NIL    
See also:
2024-12-14
Function gobject:object-interface-list-properties (gtype)
Arguments:
gtype -- a g:type-t type ID of an interface type
Returns:
The list of g:param-spec instances for all properties of an interface type.
Details:
Lists the properties of an interface type. Signals an error if the gtype type ID is not an "GInterface" type.
Examples:
(mapcar #'g:param-spec-name
        (g:object-interface-list-properties "GAction"))
=> ("enabled" "name" "parameter-type" "state" "state-type")    
See also:
2024-12-14
Function gobject:object-new (gtype &rest args)
Arguments:
gtype -- a g:type-t type ID of the g:object subtype to instantiate
args -- pairs of a property keyword and value
Details:
Creates a new instance of a g:object subtype and sets its properties. Construction parameters which are not explicitly specified are set to their default values.
Note:
In the Lisp implementation this function calls the make-instance method to create the new instance.
Examples:
(g:object-new "GtkButton" :label "text" :margin 6)
=> #<GTK:BUTTON {D941381}>    
This is equivalent to:
(make-instance 'gtk:button :label "text" :margin 6)
=> #<GTK:BUTTON {D947381}>    
See also:
2024-12-14
Function gobject:object-ref (object)
Arguments:
object -- a g:object instance
Returns:
The same g:object instance.
Details:
Increases the reference count of object.
See also:
2024-12-14
Function gobject:object-ref-count (object)
Arguments:
object -- a g:object instance
Returns:
The integer with the reference count of object.
Details:
Returns the reference count of the object.
Notes:
This function is a Lisp extension. It can be used in test files to check the number of references for objects.
See also:
2024-12-14
Function gobject:object-unref (object)
Arguments:
object -- a g:object instance
Details:
Decreases the reference count of object. When its reference count drops to 0, the object is finalized.
See also:
2024-12-14
Function gobject:object-notify (object name)
Arguments:
object -- a g:object instance
name -- a string with the name of a property installed on the class of object
Details:
Emits a "notify" signal for the property on the object.
See also:
2024-12-14
Function gobject:object-freeze-notify (object)
Arguments:
object -- a g:object instance
Details:
Increases the freeze count on the object. If the freeze count is non-zero, the emission of "notify" signals on the object is stopped. The signals are queued until the freeze count is decreased to zero. This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
See also:
2024-12-14
Function gobject:object-thaw-notify (object)
Arguments:
object -- a g:object instance
Details:
Reverts the effect of a previous call to the g:object-freeze-notify function. The freeze count is decreased on the object and when it reaches zero, all queued "notify" signals are emitted. It is an error to call this function when the freeze count is zero.
See also:
2024-12-14
Function gobject:object-data (object key)
Syntax:
(g:object-data object key) => data
(setf (g:object-data object key) data)
Arguments:
object -- a g:object instance containing the associations
key -- a string with the name of the key
data -- any Lisp object as data to associate with that key
Details:
Each object carries around a table of associations from strings to pointers. The g:object-data function gets a named field from the objects table of associations. The (setf g:object-data) function sets an association. If the object already had an association with that name, the old association will be destroyed.
Examples:
(defvar item (make-instance 'g:menu-item)) => ITEM
;; Set an integer
(setf (g:object-data item "prop") 123) => 123
(g:object-data item "prop") => 123
;; Set a Lisp list
(setf (g:object-data item "prop") '(a b c)) => (A B C)
(g:object-data item "prop") => (A B C)
;; Set a GObject
(setf (g:object-data item "prop") (make-instance 'g:menu-item))
=> #<GIO:MENU-ITEM {1001AAA263}>
(g:object-data item "prop")
=> #<GIO:MENU-ITEM {1001AAA263}>
;; Clear the association
(setf (g:object-data item "prop") nil) => nil
(g:object-data item "prop") => nil    
See also:
2024-12-14
Callback gobject:destroy-notify
Syntax:
lambda ()
Details:
Specifies the type of function which is called when a data element is destroyed. The callback function takes no argument and has no return value. See the g:object-set-data-full function for an example.
See also:
2024-12-14
Function gobject:object-set-data-full (object key func)
Arguments:
object -- a g:object instance containing the associations
key -- a string for the name of the key
func -- a g:destroy-notify callback function
Details:
Like the g:object-data function except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed.
Examples:
Set a destroy notify callback function for a window. This function is called when the window is destroyed or when the data is set to nil.
(g:object-set-data-full window "about"
                        (lambda ()
                          (gtk:window-destroy about)))    
See also:
2025-3-1
Function gobject:object-property (object name &optional gtype)
Syntax:
(g:object-property object name gtype) => value
(setf (g:object-property object name gtype) value)
Arguments:
object -- a g:object instance
name -- a string with the name of the property
gtype -- an optional g:type-t type ID of the property
value -- a value for the property
Details:
Accessor of the property of an object.
Examples:
Setting and retrieving the gtk-application-prefer-dark-theme setting.
(defvar settings (gtk:settings-default))
=> SETTINGS
(setf (g:object-property settings "gtk-application-prefer-dark-theme") t)
=> T
(g:object-property settings "gtk-application-prefer-dark-theme")
=> T    
See also:
2024-12-14

Signals

Introduction to signals

The basic concept of the signal system is that of the emission of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are available in derived types as well, so basically they are a per-type facility that is inherited.

A signal emission mainly involves invocation of a certain set of callbacks in precisely defined manner. There are two main categories of such callbacks, per-object ones and user provided ones. The per-object callbacks are most often referred to as "object method handler" or "default (signal) handler", while user provided callbacks are usually just called "signal handler".

The object method handler is provided at signal creation time, this most frequently happens at the end of an object class' creation, while user provided handlers are frequently connected and disconnected to/from a certain signal on certain object instances.

A signal emission consists of five stages, unless prematurely stopped:
  1. Invocation of the object method handler for :run-first signals.
  2. Invocation of normal user-provided signal handlers (where the after flag is not set).
  3. Invocation of the object method handler for :run-last signals.
  4. Invocation of user provided signal handlers (where the after flag is set).
  5. Invocation of the object method handler for :run-cleanup signals.
The user-provided signal handlers are called in the order they were connected in.

All handlers may prematurely stop a signal emission, and any number of handlers may be connected, disconnected, blocked or unblocked during a signal emission.

There are certain criteria for skipping user handlers in stages 2 and 4 of a signal emission. First, user handlers may be blocked. Blocked handlers are omitted during callback invocation, to return from the blocked state, a handler has to get unblocked exactly the same amount of times it has been blocked before. Second, upon emission of a :detailed signal, an additional detail argument passed in to the g:signal-emit function has to match the detail argument of the signal handler currently subject to invocation. Specification of no detail argument for signal handlers (omission of the detail part of the signal specification upon connection) serves as a wildcard and matches any detail argument passed in to emission.

While the detail argument is typically used to pass an object property name, as with "notify", no specific format is mandated for the detail string, other than that it must be non-empty.

Types and functions for signals

Bitfield gobject:signal-flags
Declaration:
(cffi:defbitfield signal-flags
  :run-first
  :run-last
  :run-cleanup
  :no-recurse
  :detailed
  :action
  :no-hooks
  :must-collect
  :deprecated)  
Values:
:run-first
Invoke the object method handler in the first emission stage.
:run-last
Invoke the object method handler in the third emission stage.
:run-cleanup
Invoke the object method handler in the last emission stage.
:no-recurse
Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted.
:detailed
The signal supports "::detail" appendices to the signal name upon handler connections and emissions.
:action
Action signals are signals that may freely be emitted on alive objects from user code via the g:signal-emit function and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.
:no-hooks
No emissions hooks are supported for this signal.
:must-collect
Varargs signal emission will always collect the arguments, even if there are no signal handlers connected.
:deprecated
The signal is deprecated and will be removed in a future version.
Details:
The signal flags are used to specify the behaviour of the signal, the overall signal description outlines how the flags control the stages of a signal emission.
See also:
2024-12-4
Bitfield gobject:connect-flags
Declaration:
(cffi:defbitfield connect-flags
  :after
  :swapped)  
Values:
:after
Whether the handler should be called before or after the default handler of the signal.
:swapped
Whether the instance and data should be swapped when calling the handler.
Details:
The connection flags are used to specify the behaviour of the connection of the signal.
See also:
2024-12-4
Struct gobject:signal-query
Superclasses:
common-lisp:structure-object, common-lisp:t
Documented Subclasses:
None
Returned by:
Slot Access Functions:
Details:
A structure holding in-depth information for a specific signal. It is filled in by the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-signal-id (instance)
Syntax:
(g:signal-query-signal-id instance) => id
Arguments:
instance -- a g:signal-query instance
id -- an unsigned integer with the signal ID of the signal being queried, or 0 if the signal to be queried was unknown
Details:
Accessor of the signal-id slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-signal-name (instance)
Syntax:
(g:signal-query-signal-name instance) => name
Arguments:
instance -- a g:signal-query instance
name -- a string with the signal name
Details:
Accessor of the signal-name slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-owner-type (instance)
Syntax:
(g:signal-query-owner-type instance) => owner-type
Arguments:
instance -- a g:signal-query instance
owner-type -- a g:type-t type ID that this signal can be emitted for
Details:
Accessor of the owner-type slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-signal-flags (instance)
Syntax:
(g:signal-query-signal-flags instance) => flags
Arguments:
instance -- a g:signal-query instance
flags -- a g:signal-flags value with the signal flags
Details:
Accessor of the signal-flags slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-return-type (instance)
Syntax:
(g:signal-query-return-type instance) => return-type
Arguments:
instance -- a g:signal-query instance
return-type -- a g:type-t type ID with the return type for user callbacks
Details:
Accessor of the return-type slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-param-types (instance)
Syntax:
(g:signal-query-param-types instance) => param-types
Arguments:
instance -- a g:signal-query instance
param-types -- a list with the individual parameter g:type-t type IDs for user callbacks
Details:
Accessor of the param-types slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Accessor gobject:signal-query-signal-detail (instance)
Syntax:
(g:signal-query-signal-detail instance) => detail
Arguments:
instance -- a g:signal-query instance
detail -- a string with the signal detail
Details:
Accessor of the signal-detail slot of the g:signal-query structure. See the g:signal-query function.
See also:
2024-12-4
Function gobject:signal-query (id)
Arguments:
id -- an unsigned integer with the signal ID of the signal to query information for
Returns:
The g:signal-query instance with the signal info.
Details:
Returns the signal info. Queries the signal system for in-depth information about a specific signal. This function will return signal-specific information. If an invalid signal ID is passed in the nil value is returned.
See also:
2024-6-19
Function gobject:signal-lookup (name itype)
Arguments:
name -- a string with the name of the signal
itype -- a g:type-t type ID that the signal operates on
Returns:
The unsigned integer with the identifying number of the signal, or 0 if no signal was found.
Details:
Given the name of the signal and the type of object it connects to, gets the identifying integer of the signal. Emitting the signal by number is somewhat faster than using the name each time. Also tries the ancestors of the given type.
Examples:
(g:signal-lookup "notify" "GObject")
=> 1
(g:signal-lookup "notify" "GtkWidget")
=> 1
(g:signal-lookup "unknown" "GObject")
=> 0    
See also:
2024-6-19
Function gobject:signal-name (id)
Arguments:
id -- an unsigned integer with the identifying number of the signal
Returns:
The string with the signal name, or nil if the signal number was invalid.
Details:
Given the identifier of the signal, finds its name. Two different signals may have the same name, if they have differing types.
Examples:
Get the signal ID for the "startup" signal and then get the name for the ID:
(g:signal-lookup "startup" "GApplication")
=> 95
(g:signal-name *)
=> "startup"    
List the IDs for an application object and retrieves the names of the signals:
(g:signal-list-ids "GApplication")
=> (97 95 96 98 99 100 101)
(mapcar #'g:signal-name *)
=> ("activate" "startup" "shutdown" "open" "command-line"
    "handle-local-options" "name-lost")    
See also:
2024-6-19
Function gobject:signal-list-ids (itype)
Arguments:
itype -- a g:type-t type ID
Returns:
The list of unsigned integer with the signal IDs.
Details:
Lists the signals by ID that a certain instance or interface type created. Further information about the signals can be acquired through the g:signal-query function.
Examples:
Get the IDs for a window widget in and show the names of the signals:
(mapcar #'g:signal-name (g:signal-list-ids "GApplication"))
=> ("activate" "startup" "shutdown" "open" "command-line"
    "handle-local-options" "name-lost")    
See also:
2024-6-19
Function gobject:signal-emit (instance detailed &rest args)
Arguments:
instance -- a g:object instance the signal is being emitted on
detailed -- a string with the detailed signal name
args -- parameters to be passed to the signal
Returns:
The return value of the signal.
Details:
Emits a signal. Note that the g:signal-emit function resets the return value to the default if no handlers are connected.
Lisp implementation:
In the Lisp implementation this function takes not the signal ID but the detailed signal name as an argument. For this case the C library has the g_signal_emit_by_name() function, which is not implemented in the Lisp binding.

At this time, setting a GParam value is not implemented in the Lisp binding. Therefore, you can not emit a "notify::<property>" signal on an instance.
See also:
2024-12-21
Function gobject:signal-connect (instance signal handler &key after)
Arguments:
instance -- a g:object instance to connect to
signal -- a string of the form "signal-name::detail"
handler -- a Lisp callback function to connect
after -- if true the handler is called after the default handler
Returns:
The unsigned long integer with the handler ID.
Details:
Connects a Lisp callback function to a signal for a particular object. The handler will be called before the default handler of the signal. If the after keyword argument is true, the handler will be called after the default handler of the signal.
Lisp implmentation:
The C library knows in addition the g_signal_connect_after() function, which is implemented with the after keyword argument.
Examples:
Connect a Lisp lambda function to the "toggled" signal of a toggle button:
(g:signal-connect button "toggled"
   (lambda (widget)
     (if (gtk:toggle-button-active widget)
         (progn
           ;; If control reaches here, the toggle button is down
         )
        (progn
           ;; If control reaches here, the toggle button is up
         ))))    
If it is necessary to have a separate function which needs user data, the following implementation is possible:
(defun separate-event-handler (widget arg1 arg2 arg3)
  [ here is the code of the event handler ] )

(g:signal-connect window destroy" (lambda (widget) (separate-event-handler widget arg1 arg2 arg3)))
If no extra data is needed, but the callback function should be separated out than it is also possible to implement something like:
(g:signal-connect window "destroy" #'separate-event-handler)    
See also:
2025-1-4
Function gobject:signal-handler-block (instance handler-id)
Arguments:
instance -- a g:object instance to block the signal handler of
handler-id -- an unsigned integer handler ID of the handler to be blocked
Details:
Blocks a handler of an instance so it will not be called during any signal emissions unless it is unblocked again. Thus "blocking" a signal handler means to temporarily deactive it. A signal handler has to be unblocked exactly the same amount of times it has been blocked before to become active again.

The handler-id has to be a valid signal handler ID, connected to a signal of instance.
See also:
2024-6-19
Function gobject:signal-handler-unblock (instance handler-id)
Arguments:
instance -- a g:object instance to unblock the signal handler of
handler-id -- an unsigned integer handler ID of the handler to be unblocked
Details:
Undoes the effect of a previous call of the g:signal-handler-block function. A blocked handler is skipped during signal emissions and will not be invoked, unblocking it (for exactly the amount of times it has been blocked before) reverts its "blocked" state, so the handler will be recognized by the signal system and is called upon future or currently ongoing signal emissions, since the order in which handlers are called during signal emissions is deterministic, whether the unblocked handler in question is called as part of a currently ongoing emission depends on how far that emission has proceeded yet.

The handler-id has to be a valid ID of a signal handler that is connected to a signal of instance and is currently blocked.
See also:
2024-6-19
Function gobject:signal-handler-disconnect (object handler-id)
Arguments:
instance -- a g:object instance to remove the signal handler from
handler-id -- an unsigned long integer with the handler ID of the handler to be disconnected
Details:
Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler-id becomes invalid and may be reused.

The handler-id has to be a valid signal handler ID, connected to a signal of instance.
See also:
2024-6-19
Function gobject:signal-handler-find (instance signal-id)
Arguments:
instance -- a g:object instance owning the signal handler to be found
signal-id -- an unsigned integer with a signal ID the handler has to be connected to
Returns:
The unsigned integer with a valid non-0 signal handler ID for a successful match.
Details:
Finds the first signal handler that matches the given signal-id. If no handler was found, 0 is returned.
Lisp implementation:
In the Lisp implementation only the search for a signal ID is implemented.
Examples:
(defvar action (make-instance 'g:simple-action)) => ACTION
;; Get the signal ID
(g:signal-lookup "activate" "GSimpleAction") => 139
;; No signal handler connected
(g:signal-handler-find action 139) => 0
;; Connect signal handler
(g:signal-connect action "activate"
                  (lambda (action param) action param))
=> 118534
(g:signal-handler-find action 139) => 118534
;; Disconnect signal handler
(g:signal-handler-disconnect action *)
(g:signal-handler-find action 139) => 0    
See also:
2024-12-4
Function gobject:signal-handler-is-connected (instance handler-id)
Arguments:
instance -- a g:object instance where a signal handler is sought
handler-id -- an unsigned long integer with the handler ID
Returns:
The boolean whether handler-id identifies a handler connected to instance.
Details:
Returns whether handler-id is the ID of a handler connected to instance.
See also:
2024-6-19
Function gobject:signal-has-handler-pending (instance id detail may-be-blocked)
Arguments:
instance -- a g:object instance whose signal handlers are sought
id -- an unsigned integer with the signal ID
detail -- a string with the detail of a signal name
may-be-blocked -- a boolean whether blocked handlers should count as match
Returns:
True if a handler is connected to the signal, false otherwise.
Details:
Returns whether there are any handlers connected to instance for the given signal ID and detail.

If detail is nil then it will only match handlers that were connected without detail. If detail is non-nil then it will match handlers connected both without detail and with the given detail. This is consistent with how a signal emitted with detail would be delivered to those handlers.

This also checks for a non-default class closure being installed, as this is basically always what you want.

One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments.
See also:
2024-6-20
Function gobject:signal-stop-emission (instance detailed)
Arguments:
instance -- a g:object instance whose signal handlers you wish to stop
detailed -- a string of the form "signal-name::detail"
Details:
Stops a current emission of the signal. This will prevent the default method from running, if the signal was :run-last and you connected normally, for example, without the :after flag for the g:signal-connect function.

Prints a warning if used on a signal which is not being emitted.
Examples:
As an example of the usage, by connecting the following handler to the "insert-text" signal, an application can convert all entry into a widget into uppercase.
;; Handler for the "insert-text" signal
(setf handlerid
      (g:signal-connect entry "insert-text"
          (lambda (editable text length position)
            (g:signal-handler-block editable handlerid)
            (gtk:editable-insert-text editable
                                      (string-upcase text)
                                      (cffi:mem-ref position :intptr))
            (g:signal-stop-emission editable "insert-text")
            (g:signal-handler-unblock editable handlerid))))    
See also:
2024-6-19

GBinding

GFlags gobject:binding-flags
Declaration:
(define-gflags "GBindingFlags" binding-flags
  (:export t
   :type-initializer "g_binding_flags_get_type")
  (:default 0)
  (:bidirectional 1)
  (:sync-create 2)
  (:invert-boolean 4))  
Values:
:default
The default binding. If the source property changes, the target property is updated with its value.
:bidirectional
Bidirectional binding. If either the property of the source or the property of the target changes, the other is updated.
:sync-create
Synchronize the values of the source and target properties when creating the binding. The direction of the synchronization is always from the source to the target.
:invert-boolean
If the two properties being bound are booleans, setting one to true will result in the other being set to false and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to the g:object-bind-property-full function.
Details:
Flags to be passed to the g:object-bind-property or g:object-bind-property-full functions.
See also:
2024-6-18
Class gobject:binding
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
flags
The flags property of type g:binding-flags (Read / Write / Construct Only)
The flags to be used to control the binding.
source
The source property of type g:object (Read / Write / Construct Only)
The object that should be used as the source of the binding.
source-property
The source-property property of type :string (Read / Write / Construct Only)
The name of the property of the source that should be used as the source of the binding.
Default value: nil
target
The target property of type g:object (Read / Write / Construct Only)
The object that should be used as the target of the binding.
target-property
The target-property property of type :string (Read / Write / Construct Only)
The name of the property of the target that should be used for the binding.
Default value: nil
Slot Access Functions:
Details:
The g:binding object is the representation of a binding between a property on a g:object instance, or source, and another property on another g:object instance, or target. Whenever the source property changes, the same value is applied to the target property. For instance, the following binding:
(g:object-bind-property object1 "property-a"
                        object2 "property-b"
                        :default)  
will cause the property named property-b of object2 to be updated every time the g:object-property function or the specific accessor changes the value of the property property-a of object1.

It is possible to create a bidirectional binding between two properties of two g:object instances, so that if either property changes, the other is updated as well, for instance:
(g:object-bind-property object1 "property-a"
                        object2 "property-b"
                        :bidirectional)  
will keep the two properties in sync.

It is also possible to set a custom transformation function, in both directions, in case of a bidirectional binding, to apply a custom transformation from the source value to the target value before applying it. For instance, the following binding:
(g:object-bind-property-full adjustment1 "value"
                             adjustment2 "value"
                             :bidirectional
                             #'celsius-to-fahrenheit
                             #'fahrenheit-to-celsius)  
will keep the value property of the two adjustments in sync. The celsius-to-fahrenheit function will be called whenever the value property of adjustment1 changes and will transform the current value of the property before applying it to the value property of adjustment2. Vice versa, the fahrenheit-to-celsius function will be called whenever the value property of adjustment2 changes, and will transform the current value of the property before applying it to the value property of adjustment1.

Note that the g:binding object does not resolve cycles by itself. A cycle like
object1:propertyA -> object2:propertyB
object2:propertyB -> object3:propertyC
object3:propertyC -> object1:propertyA  
might lead to an infinite loop. The loop, in this particular case, can be avoided if the objects emit the "notify" signal only if the value has effectively been changed. A binding is implemented using the "notify" signal, so it is susceptible to all the various ways of blocking a signal emission, like the g:signal-stop-emission or g:signal-handler-block functions.

A binding will be severed, and the resources it allocates freed, whenever either one of the g:object instances it refers to are finalized, or when the g:binding object loses its last reference. Bindings for languages with garbage collection can use the g:binding-unbind function to explicitly release a binding between the source and target properties, instead of relying on the last reference on the binding, source, and target instances to drop.
See also:
2024-12-7
Accessor gobject:binding-flags (object)
Syntax:
(g:binding-flags object) => flags
Arguments:
object -- a g:binding object
flags -- a g:binding-flags value used by the binding
Details:
Accessor of the flags slot of the g:binding class. Retrieves the flags passed when constructing the g:binding object.
See also:
2024-12-7
Accessor gobject:binding-source (object)
Syntax:
(g:binding-source object) => source
Arguments:
object -- a g:binding object
source -- a g:object source instance
Details:
Accessor of the source slot of the g:binding class. Retrieves the g:object instance used as the source of the binding.
Warning:
This function is deprecated since 2.68. Use the g:binding-dup-source function for a safer version of this function.
See also:
2024-12-7
Accessor gobject:binding-source-property (object)
Syntax:
(g:binding-source-property object) => property
Arguments:
object -- a g:binding object
property -- a string with the name of the source property
Details:
Accessor of the source-property slot of the g:binding class. Retrieves the name of the property of the source used for the binding.
See also:
2024-12-7
Accessor gobject:binding-target (object)
Syntax:
(g:binding-target object) => target
Arguments:
object -- a g:binding object
target -- a g:object target instance
Details:
Accessor of the target slot of the g:binding class. Retrieves the g:object instance used as the target of the binding.
Warning:
This function is deprecated since 2.68. Use the g:binding-dup-target function for a safer version of this function.
See also:
2024-12-7
Accessor gobject:binding-target-property (object)
Syntax:
(g:binding-target-property object) => property
Arguments:
object -- a g:binding object
property -- a string with the name of the target property
Details:
Accessor of the target-property slot of the g:binding class. Retrieves the name of the property of the target used for the binding.
See also:
2024-12-7
Function gobject:binding-dup-source (binding)
Arguments:
binding -- a g:binding object
Returns:
The g:object source instance, or nil if the source does not exist any more.
Details:
Retrieves the g:object instance used as the source of the binding. A g:binding object can outlive the g:object source instance as the binding does not hold a strong reference to the source. If the source is destroyed before the binding then this function will return nil.

Since 2.68
See also:
2024-12-7
Function gobject:binding-dup-target (binding)
Arguments:
binding -- a g:binding object
Returns:
The g:object target instance, or nil if the target does not exist any more.
Details:
Retrieves the g:object instance used as the target of the binding. A g:binding object can outlive the g:object target instance as the binding does not hold a strong reference to the target. If the target is destroyed before the binding then this function will return nil.

Since 2.68
See also:
2024-12-7
Function gobject:binding-unbind (binding)
Arguments:
binding -- a g:binding object
Details:
Explicitly releases the binding between the source and the target property expressed by binding. This function will release the reference that is being held on the binding instance. If you want to hold on to the binding instance after calling the g:binding-unbind function, you will need to hold a reference to it.
See also:
2024-12-7
Function gobject:object-bind-property (source source-prop target target-prop flags)
Arguments:
source -- a g:object source instance
source-prop -- a string with the property on source to bind
target -- a g:object target instance
target-prop -- a string with the property on target to bind
flags -- a g:binding-flags value to pass to the binding
Returns:
The g:binding instance representing the binding between the two g:object instances.
Details:
Creates a binding between source-prop on source and target-prop on target. Whenever the source-prop is changed the target-prop is updated using the same value.

If the flags argument contains the :bidirectional value then the binding will be mutual. If the target-prop property on target changes then the source-prop property on source will be updated as well.

The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can call the g:binding-unbind function on the returned g:binding object.

A g:object instance can have multiple bindings.
Examples:
This example will result in the sensitive property of the widget to be updated with the same value of the active property of the action.
(g:object-bind-property action "active" widget "sensitive" :default)  
See also:
2024-12-7
Callback gobject:binding-transform-func
Syntax:
lambda (binding from to) => result
Arguments:
binding -- a g:binding object
from -- a g:value instance in which to store the value to transform
to -- a g:value instance in which to store the transformed value
result -- True if the transformation was successful, and false otherwise.
Details:
The callback function for the g:object-bind-property-full function to be called to transform from to to. If this is the transform-to function of a binding, then from is the source property on the source object, and to is the target property on the target object. If this is the transform-from function of a :bidirectional binding, then those roles are reversed.
See also:
2024-12-7
Function gobject:object-bind-property-full (source source-prop target target-prop flags transform-to transform-from)
Arguments:
source -- a g:object source instance
source-prop -- a string with the property on source to bind
target -- a g:object target instance
target-prop -- a string with the property on target to bind
flags -- a g:binding-flags value to pass to the binding
transform-to -- a g:binding-transform-func callback function from the source to the target, or nil to use the default
transform-form -- a g:binding-transform-func callback function from the target to the source, or nil to use the default
Returns:
The g:binding object representing the binding between source and target.
Details:
Complete version of the g:object-bind-property function. Creates a binding between source-prop on source and target-prop on target, allowing you to set the transformation functions to be used by the binding.

If flags contains the :birectional value then the binding will be mutual: if target-prop on target changes then the source-prop on source will be updated as well. The transform-from function is only used in case of bidirectional bindings, otherwise it will be ignored.

The binding will automatically be removed when either the source or the target instances are finalized. This will release the reference that is being held on the g:binding object. If you want to hold on to the g:binding object, you will need to hold a reference to it. To remove the binding, call the g:binding-unbind function.

A g:object instance can have multiple bindings.
See also:
2024-12-7

Other Symbols in gobject

Symbol gobject:enum

No documentation string. Possibly unimplemented or incomplete.

Symbol gobject:flags

No documentation string. Possibly unimplemented or incomplete.

Symbol gobject:param

No documentation string. Possibly unimplemented or incomplete.

Other Macros in gobject

Macro gobject:define-gobject-subclass (gname name (&key superclass export interfaces) (&rest properties))

No documentation string. Possibly unimplemented or incomplete.

Other Classes in gobject

Class gobject:initially-unowned
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Base class that has initial 'floating' reference.

Package gio

This is the API documentation of a Lisp binding to GIO. GIO is striving to provide a modern, easy-to-use VFS API that sits at the right level in the library stack, as well as other generally useful APIs for desktop applications (such as networking and D-Bus support). The goal is to overcome the shortcomings of GnomeVFS and provide an API that is so good that developers prefer it over raw POSIX calls. Among other things that means using GObject. It also means not cloning the POSIX API, but providing higher-level, document-centric interfaces.

File Operations

GFile

GFlags gio:file-query-info-flags
Declaration:
(gobject:define-gflags "GFileQueryInfoFlags" file-query-info-flags
  (:export t
   :type-initializer "g_file_query_info_flags_get_type")
  (:none 0)
  (:nofollow-symlinks #.(ash 1 0)))  
Values:
:none
No flags set.
:nofollow-symlinks
Do not follow symlinks.
Details:
Flags used when querying a g:file-info instance.
See also:
2024-12-14
Interface gio:file
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The g:file interface is a high level abstraction for manipulating files on a virtual file system. The g:file objects are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that g:file objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations, see GInputStream and GOutputStream.

To construct a g:file object, you can use the g:file-new-for-path function if you have a path, the g:file-new-for-uri function if you have a URI, the g:file-new-for-commandline-arg function for a command line argument, the g:file-parse-name function from a UTF-8 string gotten from the g:file-get-parse-name function.

One way to think of a g:file object is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as g:file objects are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.
See also:
2024-10-12
Type gio:file-as-namestring
Details:
The g:file-as-namestring type specifier represents and performs automatic conversion between a Lisp namestring and a g:file object for files on a virtual file system. A Lisp namestring or pathname is converted to the corresponding g:file object using the g:file-parse-name function. The conversion from a g:file object back to a Lisp namestring is done with the g:file-get-parse-name function.
Examples:
Conversion of a Lisp namestring to g:file object and back:
(setf path "/home/lisp/github/glib/gio/gio.file.lisp")
=> "/home/lisp/github/glib/gio/gio.file.lisp"
(cffi:convert-to-foreign path 'g:file-as-namestring)
=> #.(SB-SYS:INT-SAP #X60BCAD6BD5B0)
(cffi:convert-from-foreign * 'g:file-as-namestring)
=> "/home/lisp/github/glib/gio/gio.file.lisp"    
See also:
2024-12-28
Function gio:file-new-for-path (path)
Arguments:
path -- a pathname or namestring containing a relative or absolute path, the path must be encoded in the GLib filename encoding
Returns:
The new g:file object for the given path.
Details:
Constructs a g:file object for a given path. This operation never fails, but the returned object might not support any I/O operation if the path argument is malformed.
See also:
2024-10-12
Function gio:file-new-for-uri (uri)
Arguments:
uri -- a UTF-8 string containing a URI
Returns:
The new g:file object for the given uri.
Details:
Constructs a g:file object for a given URI. This operation never fails, but the returned object might not support any I/O operation if the uri argument is malformed or if the URI type is not supported.
See also:
2024-10-12
Function gio:file-new-for-commandline-arg (arg)
Arguments:
arg -- a command line string
Returns:
The new g:file object.
Details:
Creates a g:file object with the given arg from the command line. The value of the arg argument 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 the arg argument 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 strings from the argv parameter as it is passed to the main function. The g_win32_get_command_line() function will return a UTF-8 version of the command line. The g:application class also uses UTF-8 but the g:application-command-line-create-file-for-arg function may be more useful for you there. It is also always possible to use this function with g:option-context instances of :filename type.
See also:
2024-10-12
Function gio:file-new-for-commandline-arg-and-cwd (arg cwd)
Arguments:
arg -- a command line string
cwd -- a string with the current working directory of the command line
Returns:
The new g:file object.
Details:
Creates a g:file object with the given arg from the command line. This function is similar to the g:file-new-for-commandline-arg function 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 command line argument was given in a context other than the invocation of the current process.

See also the g:application-command-line-create-file-for-arg function.
See also:
2024-10-12
Function gio:file-query-info (file attributes flags &optional cancellable)
Arguments:
file -- a g:file instance
attributes -- an attribute query string
flags -- a g:file-query-info-flags value
cancellable -- an optional g:cancellable instance
Returns:
The g:file-info instance for the given file or nil on error.
Details:
Gets the requested information about the specified file. The result is a g:file-info instance 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 is not possible to read a particular requested attribute from a file, it just will not be set. The attributes argument 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".

If the cancellable argument is not nil, then the operation can be cancelled by triggering the cancellable instance from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass :nofollow-symlinks in flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.
See also:
2024-12-28
Function gio:file-parse-name (parsename)
Arguments:
parsename -- a string with a file name or path to be parsed
Returns:
The new g:file object.
Details:
Constructs a g:file object with the given parsename, that is, something given by the g:file-get-parse-name function. This operation never fails, but the returned object might not support any I/O operation if parsename cannot be parsed.
See also:
2024-10-12
Function gio:file-basename (file)
Arguments:
file -- a g:file object
Returns:
The string containing the base name of the g:file object, or nil if the given g:file object is invalid.
Details:
Gets the base name, the last component of the path, for a given g:file object. If called for the toplevel 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, see the g:file-get-parse-name function.
See also:
2024-10-12
Function gio:file-path (file)
Arguments:
file -- a g:file object
Returns:
The string containing the path for the file, or nil if no such path exists.
Details:
Gets the local pathname for file, if one exists. If not nil, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O.
See also:
2024-12-30
Function gio:file-uri (file)
Arguments:
file -- a g:file object
Returns:
The string containing the URI for the file, or nil if no such path exists.
Details:
Gets the local pathname for file, if one exists. If not nil, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O.
See also:
2024-12-30
Function gio:file-get-parse-name (file)
Arguments:
file -- a g:file object
Returns:
The string containing the parse name for the file.
Details:
Gets the parse name for the file. A parse name is a UTF-8 string that describes the file such that one can get the g:file object back using the g:file-parse-name function.

This is generally used to show the g:file object 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.
See also:
2024-10-12

GFileInfo

Class gio:file-info
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The g:file-info class implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. See the file attributes document for more information on how GIO handles file attributes. To obtain a g:file-info object for a g:file object, use the g:file-query-info function or its async variant.

To change the actual attributes of a file, you should then set the attribute in the g:file-info object and call the g:file-set-attributes-from-info or g:file-set-attributes-async functions on a g:file instance.

However, not all attributes can be changed in the file. For instance, the actual size of a file cannot be changed via the g:file-info-set-size function. You may call the g:file-query-settable-attributes and g:file-query-writable-namespaces function to discover the settable attributes of a particular file at runtime.

The direct accessors, such as the g:file-info-name function, are slightly more optimized than the generic attribute accessors, such as the g:file-info-attribute-byte-string function.This optimization will matter only if calling the API in a tight loop.

It is an error to call these accessors without specifying their required file attributes when creating the g:file-info instance. Use the g:file-info-has-attribute or g:file-info-list-attributes functions to check what attributes are specified for a g:file-info instance.

The g:file-attribute-matcher instance allows for searching through a g:file-info instance for attributes.
See also:
2024-12-28
Function gio:file-info-new ()
Returns:
The newly created g:file-info instance.
Details:
Creates a new g:file-info instance.
See also:
2024-10-23
Function gio:file-info-clear-status (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-access-date-time (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-attribute-as-string (info attribute)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-attribute-boolean (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-modification-date-time (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-name (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-size (info)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-has-attribute (info attribute)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-has-namespace (info namespace)

No documentation string. Possibly unimplemented or incomplete.

Function gio:file-info-list-attributes (info &optional namespace)

No documentation string. Possibly unimplemented or incomplete.

Asynchronous I/O

GCancellable

Class gio:cancellable
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The gio:cancellable object allows operations to be cancelled. The g:cancellable object is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations.
Signal Details:
The "cancelled" signal
lambda (cancellable)    :run-last      
cancellable
The g:cancellable object.
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 the g:signal-handler-disconnect function for that handler has already returned.

There is also a problem when cancellation happen 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: the g:cancellable-connect and g:cancellable-disconnect functions which protect against problems like this.

An example of how to us this:
/* Make sure we don't do any unnecessary work if already cancelled */
if (g_cancellable_set_error_if_cancelled (cancellable))
  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.
2025-1-30
Callback gio:cancellable-source-func
Declaration:
lambda (cancellable) => result  
Values:
cancellable
The g:cancellable object.
result
It should return false if the source should be removed.
Details:
This is the function type of the callback used for the g:source instance returned by the g:cancellable-source-new function.
See also:
#2024-10-23
Function gio:cancellable-new ()
Returns:
The g:cancellable object.
Details:
Creates a new g:cancellable object. Applications that want to start one or more operations that should be cancellable should create a g:cancellable object and pass it to the operations.

One g:cancellable object can be used in multiple consecutive operations or in multiple concurrent operations.
See also:
2024-10-23
Function gio:cancellable-is-cancelled (cancellable)
Arguments:
cancellable -- a g:cancellable object, or nil
Returns:
True if cancellable is cancelled, false if called with nil or if not cancelled.
Details:
Checks if a cancellable job has been cancelled.
See also:
2024-10-23
Function gio:cancellable-source-new (cancellable)
Arguments:
cancellable -- a g:cancellable object
Returns:
The new g:source instance.
Details:
Creates a source that triggers if cancellable is cancelled and calls its g:cancellable-source-func callback function. This is primarily useful for attaching to another (non-cancellable) source with the g:source-add-child-source function to add cancellability to it.

For convenience, you can call this function with a nil value for cancellable, in which case the source will never trigger.
See also:
#2024-10-23
Function gio:cancellable-current ()
Returns:
The g:cancellable object from the top of the stack, or nil if the stack is empty.
Details:
Gets the top cancellable from the stack.
See also:
#2024-10-23
Function gio:cancellable-pop-current (cancellalbe)
Arguments:
cancellable -- a g:cancellable object
Details:
Pops cancellable off the cancellable stack (verifying that cancellable is on the top of the stack).
See also:
#2024-10-23
Function gio:cancellable-push-current (cancellable)
Arguments:
cancellable -- a g:cancellable object
Details:
Pushes cancellable onto the cancellable stack. The current cancellable can then be received using the g:cancellable-current function.

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, for example GFile operations, so you rarely have to call this yourself.
See also:
#2024-10-23
Function gio:cancellable-reset (cancellabel)
Arguments:
cancellable -- a g:cancellable object
Details:
Resets cancellable to its uncancelled state. If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined.
See also:
2024-10-23
Function gio:cancellable-cancel (cancellable)
Arguments:
cancellable -- a g:cancellable object
Details:
Will set cancellable to cancelled, and will emit the "cancelled" signal. However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.

This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the cancellable.

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 g:async-ready-callback callback function will not be invoked until the application returns to the main loop.
See also:
2024-10-23

GAsyncResult

Interface gio:async-result
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Provides a base class for implementing asynchronous function results. Asynchronous operations are broken up into two separate operations which are chained together by a g:async-ready-callback callback function. To begin an asynchronous operation, provide a g:async-ready-callback function to the asynchronous function. This callback will be triggered when the operation has completed, and must be run in a later iteration of the thread-default main context from where the operation was initiated. It will be passed a g:async-result instance filled with the details of the operation's success or failure, the object the asynchronous function was started for and any error codes returned. The asynchronous callback function is then expected to call the corresponding -finish function, passing the object the function was called for, the g:async-result instance, and optionally an error to grab any error conditions that may have occurred.

The -finish function for an operation takes the generic result of type g:async-result and returns the specific result that the operation in question yields, for example a GFileEnumerator for a "enumerate children" operation. If the result or error status of the operation is not needed, there is no need to call the -finish function. GIO will take care of cleaning up the result and error information after the g:async-ready-callback function returns. You can pass nil for the g:async-ready-callback function if you do not need to take any action at all after the operation completes. Applications may also take a reference to the g:async-result instance and call the -finish function later. However, the -finish function may be called at most once.

Example of a typical asynchronous operation flow:
void _theoretical_frobnitz_async (Theoretical         *t,
                                  GCancellable        *c,
                                  GAsyncReadyCallback  cb,
                                  gpointer             u);

gboolean _theoretical_frobnitz_finish (Theoretical *t, GAsyncResult *res, GError **e);

static void frobnitz_result_func (GObject *source_object, GAsyncResult *res, gpointer user_data) { gboolean success = FALSE;

success = _theoretical_frobnitz_finish (source_object, res, NULL);

if (success) g_printf ("Hurray!n"); else g_printf ("Uh oh!n");

...

}

int main (int argc, void *argv[]) { ...

_theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL);

... }
The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation the result is a G_IO_ERROR_CANCELLED error.

I/O Priority
Many I/O-related asynchronous operations have a priority parameter, which is used in certain cases to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between G_PRIORITY_LOW and G_PRIORITY_HIGH, with G_PRIORITY_DEFAULT as a default.
See also:
2024-10-23
Callback gio:async-ready-callback
Declaration:
lambda (source result)  
Values:
source
The g:object instance the asynchronous operation was started with.
result
The g:async-result object.
Details:
Type definition for a function that will be called back when an asynchronous operation within GIO has been completed. The g:async-ready-callback callbacks from the g:task object are guaranteed to be invoked in a later iteration of the thread-default main context where the g:task object was created. All other users of the g:async-ready-callback function must likewise call it asynchronously in a later iteration of the main context.
See also:
#2024-10-23
Function gio:async-result-user-data (result)
Arguments:
result -- a g:async-result instance
Returns:
The pointer to the user data for result.
Details:
Gets the user data from a g:async-result instance.
See also:
#2024-10-23
Function gio:async-result-source-object (result)
Arguments:
result -- a g:async-result instance
Returns:
The new reference to the source object for result, or nil if there is none.
Details:
Gets the source object from a g:async-result instance.
See also:
#2024-10-23
Function gio:async-result-is-tagged (result tag)
Arguments:
result -- a g:async-result instance
tag -- a pointer to an application defined tag
Returns:
True if result has the indicated tag, false if not.
Details:
Checks if result has the given tag, generally a function pointer indicating the result function was created by.
See also:
#2024-10-23

GTask

Class gio:task
Superclasses:
gio:async-result, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
completed
The completed property of type :boolean (read)
Whether the task has completed, meaning its callback (if set) has been invoked. This can only happen after the g:task-return-pointer function, the g:task-return-error function or one of the other return functions have been called on the task. This property is guaranteed to change from false to true exactly once. The "notify" signal for this change is emitted in the same main context as the task’s callback, immediately after that callback is invoked.
Default value: false
Returned by:
Slot Access Functions:
Details:
The g:task class represents and manages a cancellable "task".

Asynchronous operations
The most common usage of the g:task object is as the g:async-result object, to manage data during an asynchronous operation. You call the g:task-new function in the "start" method, followed by the g:task-set-task-data function and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such as the g:task-return-pointer or the g:task-return-error function, which will save the value you give it and then invoke the task's callback function in the thread-default main context where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass the g:task object back to the operation's finish function (as a g:async-result object), and you can use the g:task-propagate-pointer function or the like to extract the return value.

Here is an example for using the g:task object as a g:async-result object:
typedef struct {
  CakeFrostingType frosting;
  char *message;
} DecorationData;

static void decoration_data_free (DecorationData *decoration) { g_free (decoration->message); g_slice_free (DecorationData, decoration); }

static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; DecorationData *decoration = g_task_get_task_data (task); GError *error = NULL;

if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; }

if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) { g_object_unref (cake); // g_task_return_error() takes ownership of error g_task_return_error (task, error); g_object_unref (task); return; }

g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); }

void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; DecorationData *decoration; Cake *cake;

task = g_task_new (self, cancellable, callback, user_data); if (radius < 3) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, "%ucm radius cakes are silly", radius); g_object_unref (task); return; }

cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); if (cake != NULL) { // _baker_get_cached_cake() returns a reffed cake g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); return; }

decoration = g_slice_new (DecorationData); decoration->frosting = frosting; decoration->message = g_strdup (message); g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);

_baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); }

Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL);

return g_task_propagate_pointer (G_TASK (result), error); }
Chained asynchronous operations
The g:task object also tries to simplify asynchronous operations that internally chain together several smaller asynchronous operations. The g:task-get-cancellable, g:task-get-context, and g:task-get-priority functions allow you to get back the task's g:cancellable object, g:main-context instance, and I/O priority when starting a new subtask, so you do not have to keep track of them yourself. The g:task-attach-source function simplifies the case of waiting for a source to fire (automatically using the correct the g:main-context instance and priority).

Here is an example for chained asynchronous operations:
typedef struct {
  Cake *cake;
  CakeFrostingType frosting;
  char *message;
} BakingData;

static void decoration_data_free (BakingData *bd) { if (bd->cake) g_object_unref (bd->cake); g_free (bd->message); g_slice_free (BakingData, bd); }

static void decorated_cb (Cake *cake, GAsyncResult *result, gpointer user_data) { GTask *task = user_data; GError *error = NULL;

if (!cake_decorate_finish (cake, result, &error)) { g_object_unref (cake); g_task_return_error (task, error); g_object_unref (task); return; }

// baking_data_free() will drop its ref on the cake, so we have to // take another here to give to the caller. g_task_return_pointer (task, g_object_ref (cake), g_object_unref); g_object_unref (task); }

static gboolean decorator_ready (gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task);

cake_decorate_async (bd->cake, bd->frosting, bd->message, g_task_get_cancellable (task), decorated_cb, task);

return G_SOURCE_REMOVE; }

static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task); GError *error = NULL;

if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; }

bd->cake = cake;

// Bail out now if the user has already cancelled if (g_task_return_error_if_cancelled (task)) { g_object_unref (task); return; }

if (cake_decorator_available (cake)) decorator_ready (task); else { GSource *source;

source = cake_decorator_wait_source_new (cake); // Attach @source to @task's GMainContext and have it call // decorator_ready() when it is ready. g_task_attach_source (task, source, decorator_ready); g_source_unref (source); } }

void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, gint priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; BakingData *bd;

task = g_task_new (self, cancellable, callback, user_data); g_task_set_priority (task, priority);

bd = g_slice_new0 (BakingData); bd->frosting = frosting; bd->message = g_strdup (message); g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);

_baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); }

Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL);

return g_task_propagate_pointer (G_TASK (result), error); }
Asynchronous operations from synchronous ones You can use the g:task-run-in-thread function to turn a synchronous operation into an asynchronous one, by running it in a thread. When it completes, the result will be dispatched to the thread-default main context where the g:task object was created.

Running a task in a thread:
typedef struct {
  guint radius;
  CakeFlavor flavor;
  CakeFrostingType frosting;
  char *message;
} CakeData;

static void cake_data_free (CakeData *cake_data) { g_free (cake_data->message); g_slice_free (CakeData, cake_data); }

static void bake_cake_thread (GTask *task, gpointer source_object, gpointer task_data, GCancellable *cancellable) { Baker *self = source_object; CakeData *cake_data = task_data; Cake *cake; GError *error = NULL;

cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, cancellable, &error); if (cake) g_task_return_pointer (task, cake, g_object_unref); else g_task_return_error (task, error); }

void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task;

cake_data = g_slice_new (CakeData); cake_data->radius = radius; cake_data->flavor = flavor; cake_data->frosting = frosting; cake_data->message = g_strdup (message); task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_run_in_thread (task, bake_cake_thread); g_object_unref (task); }

Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL);

return g_task_propagate_pointer (G_TASK (result), error); }
Adding cancellability to uncancellable tasks
Finally, the g:task-run-in-thread and g:task-run-in-thread-sync functions can be used to turn an uncancellable operation into a cancellable one. If you call the g:task-return-on-cancel function, passing true, then if the task's g:cancellable object is cancelled, it will return control back to the caller immediately, while allowing the task thread to continue running in the background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you to make "GLib-friendly" asynchronous and cancellable synchronous variants of blocking APIs.

Cancelling a task:
static void
bake_cake_thread (GTask         *task,
                  gpointer       source_object,
                  gpointer       task_data,
                  GCancellable  *cancellable)
{
  Baker *self = source_object;
  CakeData *cake_data = task_data;
  Cake *cake;
  GError *error = NULL;

cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, &error); if (error) { g_task_return_error (task, error); return; }

// If the task has already been cancelled, then we don't want to add // the cake to the cake cache. Likewise, we don't want to have the // task get cancelled in the middle of updating the cache. // g_task_set_return_on_cancel() will return %TRUE here if it managed // to disable return-on-cancel, or %FALSE if the task was cancelled // before it could. if (g_task_set_return_on_cancel (task, FALSE)) { // If the caller cancels at this point, their // GAsyncReadyCallback won't be invoked until we return, // so we don't have to worry that this code will run at // the same time as that code does. But if there were // other functions that might look at the cake cache, // then we'd probably need a GMutex here as well. baker_add_cake_to_cache (baker, cake); g_task_return_pointer (task, cake, g_object_unref); } }

void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task;

cake_data = g_slice_new (CakeData);

...

task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread (task, bake_cake_thread); }

Cake * baker_bake_cake_sync (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GError **error) { CakeData *cake_data; GTask *task; Cake *cake;

cake_data = g_slice_new (CakeData);

...

task = g_task_new (self, cancellable, NULL, NULL); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread_sync (task, bake_cake_thread);

cake = g_task_propagate_pointer (task, error); g_object_unref (task); return cake; }
Porting from GSimpleAsyncResult
The g:task API attempts to be simpler than the g:simple-async-result API in several ways:
  • You can save task-specific data with the g:task-set-task-data function, and retrieve it later with the g;task-get-task-data function. This replaces the abuse of the g:simple-async-result-set-op-res-gpointer function for the same purpose with the g:simple-async-result object.
  • In addition to the task data, the g:task object also keeps track of the priority, the g:cancellable object, and the g:main-context instance associated with the task, so tasks that consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task.
  • The g:task-return-error-if-cancelled function provides simplified handling for cancellation. In addition, cancellation overrides any other g:task return value by default, like the g:simple-async-result function does when the g:simple-async-result-set-check-cancellable function is called. (You can use the g:task-set-check-cancellable function to turn off that behavior.) On the other hand, the g:task-run-in-thread function guarantees that it will always run your task_func, even if the task's g:cancellable object is already cancelled before the task gets a chance to run; you can start your task_func with a g:task-return-error-if-cancelled check if you need the old behavior.
  • The "return" methods, for example, the g:task-return-pointer function, automatically cause the task to be "completed" as well, and there is no need to worry about the "complete" vs "complete in idle" distinction. (the g:task object automatically figures out whether the task's callback can be invoked directly, or if it needs to be sent to another g:main-context instance, or delayed until the next iteration of the current g:main-context instance.)
  • The "finish" functions for the g:task object based operations are generally much simpler than the g:simple-async-result object ones, normally consisting of only a single call to the g:task-propagate-pointer function or the like. Since the g:task-propagate-pointer function "steals" the return value from the g:task object, it is not necessary to juggle pointers around to prevent it from being freed twice.
  • With the g:simple-async-result object, it was common to call the g:simple-async-result-propagate-error function from the _finish() wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it difficult for a subclass to chain to a parent class's async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriate g_task_propagate_ function. Note that wrapper methods can now use the g:async-result-legacy-propagate-error function to do old-style g:simple-async-result error-returning behavior, and the g:async-result-is-tagged function to check if a result is tagged as having come from the _async() wrapper function (for "short-circuit" results, such as when passing 0 to the g:input-stream-read-async function).
See also:
2024-10-23
Accessor gio:task-completed (object)
Syntax:
(setf (g:task-completed object) completed)
Arguments:
object -- a g:task object
completed -- a boolean whether the task has completed
Details:
Gets the value of the completed property. This changes from false to true after the task’s callback is invoked, and will return false if called from inside the callback.
See also:
#2024-10-23
Function gio:task-new (source cancellable func)
Arguments:
source -- a g:object instance that owns this task, or nil
canellable -- an optional g:cancellable instance, nil to ignore
func -- a g:async-ready-callback callback function
Returns:
A g:task instance.
Details:
Creates a g:task instance acting on source, which will eventually be used to invoke callback in the current thread-default main context.

Call this in the "start" method of your asynchronous method, and pass the g:task instance around throughout the asynchronous operation. You can use the g:task-set-task-data function to attach task-specific data to the object, which you can retrieve later via the g:task-get-task-data function.

By default, if cancellable is cancelled, then the return value of the task will always be G_IO_ERROR_CANCELLED, even if the task had already completed before the cancellation. This allows for simplified handling in cases where cancellation may imply that other objects that the task depends on have been destroyed. If you do not want this behavior, you can use the g:task-set-check-cancellable function to change it.
See also:
#2023-7-13
Function gio:task-task-data (task)

No documentation string. Possibly unimplemented or incomplete.

Function gio:task-priority (task)
Syntax:
(g:task-priority task) => priority
(setf (g:task-priority task) priority)
Arguments:
task -- a g:task instance
priority -- an integer with the priority of the request
Details:
The g:task-priority function gets the priority of the task. The (setf g:task-priority function sets the priority. If you do not call this, it will default to G_PRIORITY_DEFAULT.

This will affect the priority of g:source instances created with the g:task-attach-source function and the scheduling of tasks run in threads, and can also be explicitly retrieved later via the g:task-priority function.
See also:
#2023-7-13
Function gio:task-check-cancellable (task)
Syntax:
(g:task-check-cancellable task) => cancellable
(setf (g:task-cancellable task) cancellable)
Arguments:
task -- a g:task instance
cancellable -- a boolean whether task will check the state of its g:cancellable instance for you
Details:
The g:task-check-cancellable function gets the check-cancellable flag of task. The (setf g:task-check-cancellable) function sets or clears the check-cancellable flag. If this is true, the default, then the g:task-propagate-pointer function, etc, and the g:task-had-error function will check the g:cancellable instance of task first, and if it has been cancelled, then they will consider the task to have returned an "Operation was cancelled" error, regardless of any other error or return value the task may have had.

If cancellable is false, then task will not check the cancellable itself, and it is up to the owner of task to do this, for example using the g:task-return-error-if-cancelled function.

If you are using the g:task-set-return-on-cancel function as well, then you must leave cancellable set true.
See also:
#2023-7-13
Function gio:task-cancellable (task)
Arguments:
task -- a g:task instance
Returns:
The g:cancellable instance of task.
Details:
Gets the g:cancellable instance of the task.
See also:
#2023-7-13
Function gio:task-context (task)
Arguments:
task -- a g:task instance
Returns:
The g:main-context instance of task.
Details:
Gets the g:main-context instance that task will return its result in That is, the context that was the thread-default main context at the point when task was created.

This will always return a non-NULL value, even if the context of the task is the default g:main-context instance.
See also:
#2023-7-13
Function gio:task-source-object (task)
Arguments:
task -- a g:task instance
Returns:
A pointer to the source object of the g:task instance, or nil.
Details:
Gets the source object from task. Like the g:async-result-source-object function, but does not ref the object.
See also:
#2023-7-13
Function gio:task-return-boolean (task result)
Arguments:
task -- a g:task instance
result -- a boolean result of a task function
Details:
Sets the result of the g:task instance to result and completes the task. See the g:task-return-pointer function for more discussion of exactly what this means.
See also:
#2023-7-13
Function gio:task-return-pointer (task result)

No documentation string. Possibly unimplemented or incomplete.

Function gio:task-propagate-pointer (task)

No documentation string. Possibly unimplemented or incomplete.

Function gio:task-run-in-thread (task func)

No documentation string. Possibly unimplemented or incomplete.

Symbol gio:task-thread-func

No documentation string. Possibly unimplemented or incomplete.

File types and applications

Introduction to GContentType

A content type is a platform specific string that defines the type of a file. On UNIX it is a MIME type like "text/plain" or "image/png". On Win32 it is an extension string like ".doc", ".txt" or a perceived string like "audio". Such strings can be looked up in the registry at HKEY_CLASSES_ROOT. On macOS it is a Uniform Type Identifier such as com.apple.application.

Functions for GContentType

Function gio:content-type-equals (ctype1 ctype2)
Arguments:
ctype1 -- a content type string
ctype2 -- a content type string
Returns:
True if the two content types are identical or equivalent, false otherwise.
Details:
Compares two content types for equality.
See also:
2024-12-7
Function gio:content-type-is-a (ctype supertype)
Arguments:
ctype -- a content type string
supertype -- a content type string
Returns:
True if ctype is a kind of supertype, false otherwise.
Details:
Determines if ctype is a subset of supertype.
See also:
2024-12-7
Function gio:content-type-is-mime-type (ctype mimetype)
Arguments:
ctype -- a content type string
mimetype -- a MIME type string
Returns:
True if ctype is a kind of mimetype, false otherwise.
Details:
Determines if ctype is a subset of mimetype. Convenience wrapper around the g:content-type-is-a function.
See also:
2024-12-7
Function gio:content-type-is-unknown (ctype)
Arguments:
ctype -- a content type string
Returns:
True if ctype is the unknown content type.
Details:
Checks if the content type is the generic "unknown" content type. On UNIX this is the "application/octet-stream" MIME type, while on Win32 it is "*".
Examples:
(g:content-type-is-unknown "application/octet-stream") => T    
2024-12-7
Function gio:content-type-description (ctype)
Arguments:
ctype -- a content type string
Returns:
The string with a short description of the content type.
Details:
Gets the human readable description of the content type.
Examples:
(g:content-type-description "text/plain")
=> "Einfaches Textdokument"    
See also:
2024-12-7
Function gio:content-type-mime-type (ctype)
Arguments:
ctype -- a content type string
Returns:
The string with the registered MIME type for the given ctype, or nil if unknown.
Details:
Gets the MIME type for the content type, if one is registered.
See also:
2024-12-7
Function gio:content-type-mime-dirs ()
Syntax:
(g:content-type-mime-dirs) => dirs
Arguments:
dirs -- a list of directories to load MIME data from, including any file/ subdirectory, and with the first directory to try listed first
Details:
The g:content-type-mime-type function gets the list of directories which MIME data is loaded from. This function is intended to be used when writing tests that depend on information stored in the MIME database, in order to control the data.

Since 2.60
Notes:
The corresponding g_content_type_set_mime_dirs() setter function is not implemented in the Lisp library.
2024-12-7
Function gio:content-type-icon (ctype)
Arguments:
ctype -- a content type string
Returns:
The g:icon object corresponding to the content type.
Details:
Gets the icon for a content type.
Examples:
(g:content-type-icon "text/plain")
=> #<GIO:THEMED-ICON {10089505F3}>    
See also:
2024-12-7
Function gio:content-type-symbolic-icon (ctype)
Arguments:
ctype -- a content type string
Returns:
The symbolic g:icon object corresponding to the content type.
Details:
Gets the symbolic icon for a content type.
See also:
2024-12-7
Function gio:content-type-generic-icon-name (ctype)
Arguments:
ctype -- a content type string
Returns:
The string with the registered generic icon name for the given ctype, or nil if unknown.
Details:
Gets the generic icon name for a content type. See the shared-mime-info specification for more on the generic icon name.
Examples:
(g:content-type-generic-icon-name "text/plain")
=> "text-x-generic"    
See also:
2024-12-7
Function gio:content-type-can-be-executable (ctype)
Arguments:
ctype -- a content type string
Returns:
True if the file type corresponds to a content type that can be executable, false otherwise.
Details:
Checks if a content type can be executable. Note that for instance things like text files can be executables, that is scripts and batch files.
2024-12-7
Function gio:content-type-from-mime-type (mimetype)
Arguments:
mimetype -- a MIME type string
Returns:
The string with the content type or nil.
Details:
Tries to find a content type based on the MIME type name.
2024-12-7
Function gio:content-types-registered ()
Returns:
The list of strings with the registered content types.
Details:
Gets a list of strings containing all the registered content types known to the system.
See also:
2024-12-7

GAppInfo

GFlags gio:app-info-create-flags
Declaration:
(gobject:define-gflags "GAppInfoCreateFlags" app-info-create-flags
  (:export t
   :type-initializer "g_app_info_create_flags_get_type")
  (:none 0)
  (:needs-terminal #.(ash 1 0))
  (:supports-uris #.(ash 1 1))
  (:supports-startup-notification #.(ash 1 2)))  
Values:
:none
No flags set.
:needs-terminal
Application opens in a terminal window.
:supports-uris
Application supports URI arguments.
:supports-startup-notification
Application supports startup notification.
Details:
Flags used when creating a g:app-info instance.
See also:
2024-12-22
Interface gio:app-info
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
Information about an installed application and methods to launch it with file arguments. The g:app-info interface and the g:app-launch-context object are used for describing and launching applications installed on the system.
See also:
2024-12-22
Function gio:app-info-create-from-commandline (cmdline application flags)
Arguments:
cmdline -- a string for the commandline to use
application -- a string for the application name, or nil to use cmdline
flags -- a g:app-info-create-flags value for the flags that can specify details of the created g:app-info instance
Returns:
The new g:app-info instance.
Details:
Creates a new g:app-info instance from the given information. Note that for the cmdline argument, the quoting rules of the Exec key of the freedesktop.org Desktop Entry Specification are applied. For example, if the cmdline argument 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.
See also:
2025-2-3
Function gio:app-info-dup (info)
Arguments:
info -- a g:app-info instance
Returns:
The g:app-info instance with the duplicate of info.
Details:
Creates a duplicate of an application info.
See also:
2024-12-22
Function gio:app-info-equal (info1 info2)
Arguments:
info1 -- a first g:app-info instance
info2 -- a second g:app-info instance
Returns:
True if info1 is equal to info2, false otherwise.
Details:
Checks if two application infos are equal.
See also:
2024-12-22
Function gio:app-info-id (info)
Arguments:
info -- a g:app-info instance
Returns:
The string containing the ID of the application.
Details:
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 nil, depending on how info has been constructed.
See also:
2024-12-22
Function gio:app-info-name (info)
Arguments:
info -- a g:app-info instance
Returns:
The string with the the name of the application for info.
Details:
Gets the installed name of the application.
See also:
2024-12-22
Function gio:app-info-display-name (info)
Arguments:
info -- a g:app-info instance
Returns:
The string with the the display name of the application for info, or the name of the application if no display name is available.
Details:
Gets the display name of the application. The display name is often more descriptive to the user than the application name itself.
See also:
2024-12-22
Function gio:app-info-description (info)
Arguments:
info -- a g:app-info instance
Returns:
The string containing a description of the application info, or nil if none.
Details:
Gets a human readable description of an installed application.
See also:
2024-12-22
Function gio:app-info-executable (info)
Arguments:
info -- a g:app-info instance
Returns:
The string containing the application binaries name of info.
Details:
Gets the name of the executable for the installed application.
See also:
2024-12-22
Function gio:app-info-commandline (info)
Arguments:
info -- a g:app-info instance
Returns:
The string containing the commandline of info, or nil if this information is not available.
Details:
Gets the commandline with which the application will be started.
See also:
2024-12-22
Function gio:app-info-icon (info)
Arguments:
info -- a g:app-info instance
Returns:
The default g:icon object for info or nil if there is no default icon.
Details:
Gets the icon for the application.
See also:
2024-12-22
Function gio:app-info-launch (info files context)
Arguments:
info -- a g:app-info instance
files -- a list of g:file objects
context -- a g:app-launch-context instance or nil
Returns:
True on successful launch, false otherwise.
Details:
Launches the application. Passes files to the launched application as arguments, using the optional context argument to get information about the details of the application launcher, like what screen it is on. To launch the application without arguments pass nil for the 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 g:file object, 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 the g:app-info-launch-uris function instead.

The launched application inherits the environment of the launching process, but it can be modified with the g:app-launch-context-setenv function and the g:app-launch-context-unsetenv function.

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.
See also:
2024-12-22
Function gio:app-info-supports-files (info)
Arguments:
info -- a g:app-info instance
Returns:
True if info supports files.
Details:
Checks if the application accepts files as arguments.
See also:
2024-12-22
Function gio:app-info-supports-uris (info)
Arguments:
info -- a g:app-info instance
Returns:
True if info supports URIs.
Details:
Checks if the application supports reading files and directories from URIs.
See also:
2024-12-22
Function gio:app-info-launch-uris (info uris context)
Arguments:
info -- a g:app-info instance
uris -- a list of strings with the containing URIs to launch
context -- a g:app-launch-context instance or nil
Returns:
True on successful launch, false otherwise.
Details:
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.

To launch the application without arguments pass a nil 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.
See also:
#2024-12-22
Function gio:app-info-should-show (info)
Arguments:
info -- a g:app-info instance
Returns:
True if info should be shown, false otherwise.
Details:
Checks if the application info should be shown in menus that list available applications.
See also:
2024-12-22
Function gio:app-info-can-delete (info)
Arguments:
info -- a g:app-info instance
Returns:
True if info can be deleted.
Details:
Obtains the information whether the application info can be deleted. See the g:app-info-delete function.
See also:
#2024-12-22
Function gio:app-info-delete (info)
Arguments:
info -- a g:app-info instance
Returns:
True if info has been deleted.
Details:
Tries to delete an application info.

On some platforms, there may be a difference between user-defined application infos which can be deleted, and system-wide ones which cannot. See the g:app-info-can-delete function.
See also:
#2024-12-22
Function gio:app-info-reset-type-associations (content-type)
Function gio:app-info-set-as-default-for-type (info content-type)
Arguments:
info -- a g:app-info instance
content-type -- a string for the content type
Returns:
True on success, false on error.
Details:
Sets the application as the default handler for a given content type.
See also:
#2025-2-3
Function gio:app-info-set-as-default-for-extension (info extension)
Arguments:
info -- a g:app-info instance
extension -- a string containing the file extension, without the dot
Returns:
True on success, false on error.
Details:
Sets the application as the default handler for the given file extension.
See also:
#2024-12-22
Function gio:app-info-set-as-last-used-for-type (info content-type)
Arguments:
info -- a g:app-info instance
content-type -- a string with the content type
Returns:
True on success, false on error.
Details:
Sets the application as the last used application for a given content type. This will make the application appear as first in the list returned by the g:app-info-recommended-for-type function, regardless of the default application for that content type.
See also:
#2024-12-22
Function gio:app-info-add-supports-type (info content-type)
Arguments:
info -- a g:app-info instance
content-type -- a string with the content type
Returns:
True on success, false on error.
Details:
Adds a content type to the application information to indicate the application is capable of opening files with the given content type.
See also:
#2024-12-22
Function gio:app-info-can-remove-supports-type (info)
Arguments:
info -- a g:app-info instance
Returns:
True if it is possible to remove supported content types from a given info, false if not.
Details:
Checks if a supported content type can be removed from an application.
See also:
#2024-12-22
Function gio:app-info-remove-supports-type (info content-type)
Arguments:
info -- a g:app-info instance
content-type -- a string with the content type
Returns:
True on success, false on error.
Details:
Removes a supported content type from an application information, if possible.
See also:
#2024-12-22
Function gio:app-info-supported-types (info)
Arguments:
info -- a g:app-info instance
Returns:
The list of strings with the content types.
Details:
Retrieves the list of content types that info claims to support. If this information is not provided by the environment, this function will return nil. This function does not take in consideration associations added with the g:app-info-add-supports-type function, but only those exported directly by the application.
See also:
2024-12-22
Function gio:app-info-all ()
Returns:
The list of g:app-info instances.
Details:
Gets a list of all application infos for 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 the g:app-info-should-show function. The returned list does not include applications which have the Hidden key set.
See also:
2024-12-22
Function gio:app-info-all-for-type (content-type)
Arguments:
content-type -- a string with the content type
Returns:
The list of g:app-info instances for the given content-type or nil on error.
Details:
Gets a list of all application infos for a given content type, including the recommended and fallback application infos. See the g:app-info-recommended-for-type and g:app-info-fallback-for-type functions.
See also:
2024-12-22
Function gio:app-info-default-for-type (content-type must-support-uris)
Arguments:
content-type -- a string with the content type
must-support-uris -- if true, the application info is expected to support URIs
Returns:
The g:app-info instance for the given content-type or nil on error.
Details:
Gets the default application info for a given content type.
See also:
2024-12-22
Function gio:app-info-default-for-uri-scheme (uri-scheme)
Arguments:
uri-scheme -- a string containing a URI scheme
Returns:
The g:app-info instance for the given uri-scheme or nil on error.
Details:
Gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', for example, "http", "ftp" or "sip".
See also:
2024-12-22
Function gio:app-info-fallback-for-type (content-type)
Arguments:
content-type -- a string with the content type
Returns:
The list of g:app-info instances for the given content-type or nil on error.
Details:
Gets a list of fallback application infos for a given content type, that is, those applications which claim to support the given content type by MIME type subclassing and not directly.
See also:
2024-12-22
Arguments:
content-type -- a string with the content type
Returns:
The list of g:app-info instances for the given content-type or nil on error.
Details:
Gets a list of recommended application infos for a given content type, that is, 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, that is, the last one for which the g:app-info-set-as-last-used-for-type function has been called.
See also:
2024-12-22
Function gio:app-info-launch-default-for-uri (uri &optional context)
Arguments:
uri -- a string with the URI to show
context -- an optional g:app-launch-context object, the argument can be nil, that is the default
Returns:
True on sucess, false on error.
Details:
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.
See also:
2024-12-22
Function gio:app-info-launch-default-for-uri-async (uri context cancellable func)
Arguments:
uri -- a string with the URI to show
context -- an optional g:app-launch-context object, or nil
cancellable -- a g:cancellable object
func -- a g:async-ready-callback callback function to call when the request is done
Details:
Asynchronous version of the g:app-info-launch-default-for-uri function. This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user.

This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation.
See also:
2024-12-22
Function gio:app-info-launch-default-for-uri-finish (result)
Arguments:
result -- a g:async-result object
Returns:
True if the launch was successful, false otherwise
Details:
Finishes an asynchronous g:app-info-launch-default-for-uri-async operation.
See also:
2025-1-4
Class gio:app-launch-context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
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.
Signal Details:
The "launch-failed" signal
lambda (context startup-notify-id)    :run-last      
context
The g:app-launch-context object emitting the signal.
startup-notify-id
The string with the startup notification ID for the failed launch.
The signal is emitted when a g:app-info launch fails. The startup notification ID is provided, so that the launcher can cancel the startup notification.
The "launch-started" signal
lambda (context info platform-data)    :run-first     
context
The g:app-launch-context object emitting the signal.
info
The g:app-info instance that is about to be launched.
platform-data
The g:variant parameter with additional platform specific data for this launch. The argument can be NULL.
The signal is emitted when a g:app-info instance is about to be launched. If non-null the platform-data is a g:variant dictionary mapping strings to variants, that is a{sv}, which contains additional, platform specific data about this launch. On UNIX, at least the startup-notification-id keys will be present.

The value of the startup-notification-id key (type s) is a startup notification ID corresponding to the format from the startup notification specification. It allows tracking the progress of the launchee through startup.

It is guaranteed that this signal is followed by either a "launched" or "launch-failed" signal.

Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance.

The default handler is called after the handlers added via the g:signal-connect function.

Since 2.72
The "launched" signal
lambda (context info platform-data)    :run-last      
context
The g:app-launch-context object emitting the signal.
info
The g:app-info object that was just launched.
platform-data
The g:variant parameter with additional platform specific data for this launch.
The signal is emitted when a g:app-info object is successfully launched. The argument platform-data is a g:variant dictionary mapping strings to variants, that is 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.
g:app-launch-context-new
See also:
2025-2-3
Function gio:app-launch-context-new ()
Returns:
The g:app-launch-context instance.
Details:
Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as a gdk:app-launch-context object.
See also:
2024-12-22
Function gio:app-launch-context-setenv (context variable value)
Arguments:
context -- a g:app-launch-context instance
variable -- a string with the enviroment variable to set
value -- a string with the value for to set the variabel to
Details:
Arranges for variable to be set to value in the child's environment when context is used to launch an application.
See also:
#2024-12-22
Function gio:app-launch-context-unsetenv (context variable)
Arguments:
context -- a g:app-launch-context instance
variable -- a string with the enviroment variable to remove
Details:
Arranges for variable to be unset in the child's environment when context is used to launch an application.
See also:
#2024-12-22
Function gio:app-launch-context-environment (context)
Arguments:
context -- a g:app-launch-context instance
Returns:
The list of strings with the child's enviroment.
Details:
Gets the complete environment variable list to be passed to the child process when context is used to launch an application. This is a list of strings, where each string has the form KEY=VALUE.
See also:
#2024-12-22
Function gio:app-launch-context-display (context info files)
Arguments:
context -- a g:app-launch-context instance
info -- a g:app-info instance
files -- a list of g:file objects
Returns:
The display string for the display.
Details:
Gets the display string for the context. This is used to ensure new applications are started on the same display as the launching application, by setting the DISPLAY environment variable.
See also:
#2024-12-22
Function gio:app-launch-context-startup-notify-id (context info files)
Arguments:
context -- a g:app-launch-context instance
info -- a g:app-info instance
files -- a list of g:file objects
Returns:
The string with a startup notification ID for the application, or nil if not supported.
Details:
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.
See also:
#2024-12-22
Function gio:app-launch-context-launch-failed (context startup-notify-id)
Arguments:
context -- a g:app-launch-context instance
startup-notify-id -- a string with the startup notification ID
Details:
Called when an application has failed to launch, so that it can cancel the application startup notification started in the g:app-launch-context-startup-notify-id function.
See also:
#2024-12-22

Icons

GIcon

Interface gio:icon
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The g:icon interface 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.

The g:icon interface does not provide the actual pixmap for the icon as this is out of the scope of GIO, however implementations of the g:icon interface may contain the name of an icon, see the g:themed-icon class, or the path to an icon, see the g:loadable-icon class.

To obtain a hash of a g:icon object, see the g:icon-hash function. To check if two g:icon objects are equal, see the g:icon-equal function.

For serializing a g:icon object, use the g:icon-serialize and g:icon-deserialize functions.

If you want to consume the g:icon interface, for example, in a toolkit, you must be prepared to handle at least the three following cases: g:loadable-icon, g:themed-icon and g:emblemed-icon classes. It may also make sense to have fast-paths for other cases, like handling the gdk-pixbuf:pixbuf object directly, for example, but all compliant g:icon implementations outside of GIO must implement the g:loadable-icon class.

If your application or library provides one or more g:icon implementations you need to ensure that your new implementation also implements the g:loadable-icon class. Additionally, you must provide an implementation of the g:icon-serialize function that gives a result that is understood by the g:icon-deserialize function, yielding one of the built-in icon types.
See also:
2024-10-23
Function gio:icon-hash (icon)
Arguments:
icon -- a g:icon object
Returns:
The unsigned integer containing a hash for the icon, suitable for use in a hash table or similar data structure.
Details:
Gets a hash for an icon.
See also:
2024-10-23
Function gio:icon-equal (icon1 icon2)
Arguments:
icon1 -- a first g:icon object
icon2 -- a second g:icon object
Returns:
True if icon1 is equal to icon2, false otherwise.
Details:
Checks if two icons are equal.
See also:
2024-10-23
Function gio:icon-to-string (icon)
Arguments:
icon -- a g:icon object
Returns:
The UTF-8 string or nil if icon cannot be serialized.
Details:
Generates a textual representation of the icon that can be used for serialization such as when passing the icon to a different process or saving it to persistent storage. Use the g:icon-new-for-string function to get the icon back from the returned string.

The encoding of the returned string is proprietary to a g:icon object except in the following two cases
  • If icon is a g:file-icon object, the returned string is a native path, such as /path/to/my icon.png, without escaping if the g:file object for icon is a native file. If the file is not native, the returned string is the result of the g:file-uri function, such as sftp://path/to/my%20icon.png.
  • If icon is a g:themed-icon object with exactly one name, the encoding is simply the name, such as network-server.
See also:
2024-10-23
Function gio:icon-new-for-string (str)
Arguments:
str -- a string obtained using the g:icon-to-string function
Returns:
The object implementing the g:icon interface or nil if an error is set.
Details:
Generate a g:icon object from the str argument. This function can fail if the str argument is not valid - see the g:icon-to-string function for discussion.

If your application or library provides one or more g:icon implementations you need to ensure that each type is registered with the type system prior to calling this function.
See also:
2024-11-21
Function gio:icon-serialize (icon)
Arguments:
icon -- a g:icon object
Returns:
The g:variant parameter, or nil when serialization fails. The g:variant parameter will not be floating.
Details:
Serializes a g:icon object into a g:variant parameter. An equivalent g:icon object can be retrieved back by calling the g:icon-deserialize function on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the g:variant parameter between processes on the same machine, as opposed to over the network, and within the same file system namespace.
See also:
2024-10-23
Function gio:icon-deserialize (value)
Arguments:
value -- a g:variant parameter created with the g:icon-serialize function
Returns:
The g:icon object, or nil when deserialization fails.
Details:
Deserializes a g:icon object previously serialized using the g:icon-serialize function.
See also:
2024-10-23

GFileIcon

Class gio:file-icon
Superclasses:
gio:icon, gio:loadable-icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
file
The file property of type g:file (Read / Write / Construct Only)
The file containing the icon.
Returned by:
Slot Access Functions:
Details:
The g:file-icon class specifies an icon by pointing to an image file to be used as icon.
See also:
2024-12-18
Accessor gio:file-icon-file (object)
Syntax:
(g:file-icon-file object) => file
Arguments:
object -- a g:file-icon object
file -- a g:file object
Details:
Accessor of the file slot of the g:file-icon class. The g:file-icon-file function gets the g:file object associated with the given icon.
See also:
2024-10-23
Function gio:file-icon-new (file)
Arguments:
file -- a g:file object
Returns:
The g:icon object for the given file, or nil on error.
Details:
Creates a new icon for a file.
See also:
2024-10-23

GLoadableIcon

Interface gio:loadable-icon
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
Extends the g:icon interface and adds the ability to load icons from streams.
See also:
2024-10-23

GThemedIcon

Class gio:themed-icon
Superclasses:
gio:icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
name
The name property of type :string (Write / Construct Only)
The icon name.
Default value: nil
names
The names property of type g:strv-t (Read / Write / Construct Only)
The list of strings with the icon names.
use-default-fallbacks
The use-default-fallbacks property of type :boolean (Read / Write / Construct Only)
Whether to use the default fallbacks found by shortening the icon name at '-' characters.
Default value: nil
Returned by:
Slot Access Functions:
Details:
The g:themed-icon class is an implementation of the g:icon interface that supports icon themes. The g:themed-icon class contains a list of all of the icons present in an icon theme, so that icons can be looked up quickly. The g:themed-icon class does not provide actual pixmaps for icons, just the icon names.
See also:
2024-10-23
Accessor gio:themed-icon-name (object)
Syntax:
(g:themed-icon-name object) => name
(setf (g:themed-icon-name object) name)
Arguments:
object -- a g:themed-icon object
name -- a string with the icon name
Details:
Accessor of the name slot of the g:themed-icon class.
See also:
2024-10-23
Accessor gio:themed-icon-names (object)
Syntax:
(g:themed-icon-names object) => names
(setf (g:themed-icon-names object) names)
Arguments:
object -- a g:themed-icon object
names -- a list of strings with icon names
Details:
Accessor of the names slot of the g:themed-icon class. Gets the names of icons from within object.
See also:
2024-10-23
Accessor gio:themed-icon-use-default-fallbacks (object)
Syntax:
(g:themed-icon-use-default-fallbacks object) => setting
(setf (g:themed-icon-use-default-fallbacks object) setting)
Arguments:
object -- a g:themed-icon object
setting -- a boolean whether to use default fallbacks
Details:
Accessor of the use-default-fallbacks slot of the g:themed-icon class. Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the names list has more than one element, ignores any past the first.
Examples:
For example, if the icon name was "gnome-dev-cdrom-audio", the list would become
'("gnome-dev-cdrom-audio"
  "gnome-dev-cdrom"
  "gnome-dev"
  "gnome")    
See also:
2024-10-23
Function gio:themed-icon-new (name)
Arguments:
name -- a string containing an icon name
Returns:
The new g:themed-icon object.
Details:
Creates a new themed icon for the icon name.
See also:
2024-10-23
Function gio:themed-icon-new-from-names (&rest names)
Arguments:
names -- strings containing icon names
Returns:
The new g:themed-icon object.
Details:
Creates a new themed icon for names.
See also:
2024-10-23
Function gio:themed-icon-new-with-default-fallbacks (name)
Arguments:
name -- a string containing an icon name
Returns:
The new g:themed-icon object.
Details:
Creates a new themed icon for name, and all the names that can be created by shortening the icon name at '-' characters.
Examples:
In the following example, icon1 and icon2 are equivalent:
(let* ((names (list "gnome-dev-cdrom-audio"
                    "gnome-dev-cdrom"
                    "gnome-dev"
                    "gnome"))
       (icon1 (g:themed-icon-new-from-names names))
       (icon2 (g:themed-icon-new-with-default-fallbacks
                "gnome-dev-cdrom-audio")))
  ... )    
See also:
2025-3-2
Function gio:themed-icon-prepend-name (icon name)
Arguments:
icon -- a g:themed-icon object
name -- a string with the name of the icon to prepend to list of icons from within icon
Details:
Prepend a name to the list of icons from within icon. Note that doing so invalidates the hash computed by prior calls to the g:icon-hash function.
See also:
2024-10-23
Function gio:themed-icon-append-name (icon name)
Arguments:
icon -- a g:themed-icon object
name -- a string with the name of the icon to append to list of icons from within icon
Details:
Append a name to the list of icons from within icon. Note that doing so invalidates the hash computed by prior calls to the g:icon-hash function.
See also:
2024-10-23

GEmblem

GEnum gio:emblem-origin
Declaration:
(gobject:define-genum "GEmblemOrigin" emblem-origin
  (:export t
   :type-initializer "g_emblem_origin_get_type")
  :unknown
  :device
  :livemetadata
  :tag)  
Values:
:unkown
Emblem of unknown origin.
:device
Emblem adds device-specific information.
:livemetadata
Emblem depicts live metadata, such as "readonly".
:tag
Emblem comes from a user-defined tag, for example, set by nautilus (in the future).
Details:
The g:emblem-origin enumeration is used to add information about the origin of the emblem to a g:emblem object.
See also:
2024-10-23
Class gio:emblem
Superclasses:
gio:icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
icon
The icon property of type g:object (Read / Write / Construct Only)
The actual icon of the emblem.
origin
The origin property of type g:emblem-origin (Read / Write / Construct Only)
Tells which origin the emblem is derived from.
Default value: :unkown
Returned by:
Slot Access Functions:
Details:
The g:emblem class is an implementation of the g:icon class that supports having an emblem, which is an icon with additional properties. It can than be added to a g:emblemed-icon object.

Currently, only metainformation about the origin of the emblem is supported. More may be added in the future.
See also:
2024-10-23
Accessor gio:emblem-icon (object)
Arguments:
object -- a g:emblem object from which the icon should be extracted
Details:
Accessor of the icon slot of the g:emblem class. The g:emblem-icon function gives back the icon from the emblem.
See also:
2024-10-23
Accessor gio:emblem-origin (object)
Arguments:
object -- a g:emblem object
Details:
Accessor of the origin slot of the g:emblem class. The g:emblem-origin function gets the origin of the emblem.
See also:
204-10-23
Function gio:emblem-new (icon)
Arguments:
icon -- a g:icon object containing the icon
Returns:
The new g:emblem object for icon.
Details:
Creates a new emblem for an icon.
See also:
2024-10-23
Function gio:emblem-new-with-origin (icon origin)
Arguments:
icon -- a g:icon object containing the icon
origin -- a g:emblem-origin value defining the origin of the emblem
Returns:
The new g:emblem object for icon.
Details:
Creates a new emblem for an icon.
See also:
2024-10-23

GEmblemedIcon

Class gio:emblemed-icon
Superclasses:
gio:icon, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
gicon
The gicon property of type g:icon (Read / Write / Construct Only)
The icon to attach emblems to.
Returned by:
Slot Access Functions:
Details:
The g:emblemed-icon class is an implementation of the g:icon interface that supports adding an emblem to an icon. The addition of more than one emblem to an icon is possible using the g:emblemed-icon-add-emblem function.

Note that the g:emblemed-icon class allows no control over the position of the emblems. See also the g:emblem class for more information.
See also:
2024-10-23
Accessor gio:emblemed-icon-gicon (object)
Syntax:
(g:emblemed-icon-gicon object) => gicon
(setf (g:emblemend-icon-gicon object) gicon)
Arguments:
object -- a g:emblemed-icon object
gicon -- a g:icon object to attach emblems to
Details:
Accessor of the gicon slot of the g:emblemed-icon class.
See also:
2024-10-23
Function gio:emblemed-icon-new (icon emblem)
Arguments:
icon -- a g:icon object
emblem -- a g:emblem object, or nil
Details:
Creates a new emblemed icon for icon with the emblem emblem.
See also:
2024-10-23
Function gio:emblemed-icon-icon (emblemed)
Arguments:
emblemed -- a g:emblemed-icon object
Returns:
The g:icon object that is owned by emblemed.
Details:
Gets the main icon for the emblemed icon.
See also:
2024-10-23
Function gio:emblemed-icon-emblems (emblemed)
Arguments:
emblemed -- a g:emblemed-icon object
Returns:
The list of g:emblem objects that is owned by emblemed.
Details:
Gets the list of emblems for the emblemed icon.
See also:
2024-10-23
Function gio:emblemed-icon-add-emblem (emblemed emblem)
Arguments:
emblemed -- a g:emblemed-icon object
emblem -- a g:emblem object
Details:
Adds emblem to the list emblems for the emblemed icon.
See also:
2024-10-23
Function gio:emblemed-icon-clear-emblems (emblemed)
Arguments:
emblemed -- a g:emblemed-icon object
Details:
Removes all the emblems from the emblemed icon.
See also:
2024-10-23

Settings



GSettings

Class gio:settings
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
backend
delay-apply
has-unapplied
path
schema
schema-id
settings-schema
Details:
The g: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 the g:settings API is typically extremely fast: on approximately the same order of magnitude (but slower than) a GHashTable lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service does not even need to be started in this case. For this reason, you should only ever modify GSettings keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup - for example, when setting the initial value of preferences widgets. The built-in g:settings-bind functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets.

When creating a GSettings instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information.

Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be ‘relocatable’, i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an ‘account’, and you want to be able to store a arbitrary number of accounts.

Paths must start with and end with a forward slash character (/) and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are /org/gtk/settings/file-chooser/ and /ca/desrt/dconf-editor/. Paths should not start with /apps/, /desktop/ or /system/ as they often did in GConf.

Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores values as GVariant, and allows any GVariantType for keys. Key names are restricted to lowercase characters, numbers and -. Furthermore, the names must begin with a lowercase character, must not end with a -, and must not contain consecutive dashes.

Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the gettext-domain attribute of the <schemalist> or <schema> elements and the category that is specified in the l10n attribute of the <default> element. The string which is translated includes all text in the <default> element, including any surrounding quotation marks.

The l10n attribute must be set to messages or time, and sets the locale category for translation. The messages category should be used by default; use time for translatable date or time formats. A translation comment can be added as an XML comment immediately above the <default> element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation context attribute can be set on the <default> element to disambiguate multiple defaults which use the same string.

2025-3-12
Generic Function gio:settings-backend (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-delay-apply (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-has-unapplied (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-path (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-schema (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-schema-id (object)

No documentation string. Possibly unimplemented or incomplete.

Generic Function gio:settings-settings-schema (object)

No documentation string. Possibly unimplemented or incomplete.

Function gio:settings-new (schema)

No documentation string. Possibly unimplemented or incomplete.

Function gio:settings-new-with-path (schema path)

No documentation string. Possibly unimplemented or incomplete.



Resources

GFlags gio:resource-flags
Declaration:
(gobject:define-gflags "GResourceFlags" resource-flags
  (:export t
   :type-initializer "g_resource_flags_get_type")
  (:none 0)
  (:compressed #.(ash 1 0)))  
Values:
:none
No flags set.
:compressed
The file is compressed.
Details:
The g:resource-flags flags give information about a particular file inside a resource bundle.
See also:
2024-5-12
GFlags gio:resource-lookup-flags
Declaration:
(gobject:define-gflags "GResourceLookupFlags" resource-lookup-flags
  (:export t
   :type-initializer "g_resource_lookup_flags_get_type")
  (:none 0))  
Values:
:none
No flags set.
Details:
The g:resource-lookup-flags flags determine how resource path lookups are handled.
See also:
2024-5-12
GBoxed gio:resource
Declaration:
(glib:define-gboxed-opaque resource "GResource"
  :export t
  :type-initializer "g_resource_get_type"
  :alloc (error "GResource cannot be created from the Lisp side"))  
Details:
Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance gtk:builder .ui files, splashscreen images, g:menu markup XML, CSS files, icons, etc. These are often shipped as files in $datadir/appname, or manually included as literal strings in the code.

The g:resource API and the 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, for example, for larg 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 g:resource 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 program which takes an XML file that describes the bundle, and a set of files that the XML references. These are combined into a binary resource bundle.

An example resource description:
<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/org/gtk/Example">
    <file>data/splashscreen.png</file>
    <file compressed="true">dialog.ui</file>
    <file preprocess="xml-stripblanks">menumarkup.xml</file>
    <file alias="example.css">data/example.css</file>
  </gresource>
</gresources>  
This will create a resource bundle with the following files:
/org/gtk/Example/data/splashscreen.png
/org/gtk/Example/dialog.ui
/org/gtk/Example/menumarkup.xml
/org/gtk/Example/example.css  
Note that all resources in the process share the same namespace, so use Java-style path prefixes, like in the above example, to avoid conflicts.

You can then use the glib-compile-resources program to compile the XML to a binary bundle that you can load with the g:resource-load function. 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. The get_resource() function returns the generated g:resource instance. The register and unregister functions register the resource so its files can be accessed using the g:resources-lookup-data function.

Once a g:resource instance has been created and registered all the data in it can be accessed globally in the process by using API calls like the g_resources_open_stream() function to stream the data or the g:resources-lookup-data function to get a direct pointer to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with GFile to access the resource data.

Some higher-level APIs, such as the gtk:application class, 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 g:resource instance 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, for example, 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. It is possible to use the G_RESOURCE_OVERLAYS environment variable to selectively overlay resources with replacements from the filesystem. It is a G_SEARCHPATH_SEPARATOR separated list of substitutions to perform during resource lookups.

A substitution has the form:
/org/gtk/libgtk=/home/desrt/gtk-overlay  
The part before the = is the resource subpath for which the overlay applies. The part after is a filesystem path which contains files and subdirectories as you would like to be loaded as resources with the equivalent names.

In the example above, if an application tried to load a resource with the resource path /org/gtk/libgtk/ui/gtkdialog.ui then the g:resource instance 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.
See also:
2024-5-12
Macro gio:with-resource ((resource path) &body body)
Syntax:
(g:with-resource (resource path) body) => result
Arguments:
resource -- a g:resource instance to create and register
path -- a pathname or namestring with the path of a file to load
body -- a body that uses the binding resource
Details:
The g:with-resource macro allocates a new g:resource instance, loads the resource from a file, register the resource with the process-global set of resources and executes the body that uses the resources. After execution of the body the resource is unregistered from the process-global set of resources.
See also:
2024-5-12
Macro gio:with-resources (vars &body body)
Syntax:
(g:with-resources ((resource1 path1) ... (resourcen pathn)) body) => result
Arguments:
resource1 ... resourcen -- newly created g:resource instances
path1 ... pathn -- pathnames or namestrings with the path of a file to load
body -- a body that uses the bindings resource1 ... resourcen
Details:
The g:with-resources macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro. See also the g:with-resource documentation.
See also:
2024-5-12
Function gio:resource-load (path)
Arguments:
path -- a pathname or namestring with the path of a file to load, in the GLib filenname encoding
Returns:
The new g:resource instance.
Details:
Loads a binary resource bundle and creates a g:resource instance 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 the g:resources-register function. The function signals an error if the resource file does not exist.
See also:
2024-11-21
Function gio:resource-lookup-data (resource path lookup)
Arguments:
resource -- a g:resource instance
path -- a string with a pathname inside the resource
lookup -- a g:resource-lookup-flags value
Returns:
The pointer to the data, cffi:null-pointer on error.
Details:
Looks for a file at the specified path in the resource and returns a pointer 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 data.

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.

The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21
Function gio:resource-enumerate-children (resource path lookup)
Arguments:
resource -- a g:resource instance
path -- a string with a pathname inside the resource
lookup -- a g:resource-lookup-flags value
Returns:
The list of strings.
Details:
Returns all the names of children at the specified path in the resource. The return result is a list of strings. The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21
Function gio:resource-info (resource path lookup)
Arguments:
resource -- a g:resource instance
path -- a string with a pathname inside the resource
lookup -- a g:resource-lookup-flags value
Returns:
size -- an integer with the length of the contents of the file
flags -- an unsigned integer with the flags about the file
Details:
Looks for a file at the specified path in the resource and if found returns information about it. The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21
Function gio:resources-register (resource)
Arguments:
resource -- a g:resource instance
Details:
Registers the resource with the process-global set of resources. Once a resource is registered the files in it can be accessed with the global resource lookup functions like the g:resources-lookup-data function.
See also:
2024-5-12
Function gio:resources-unregister (resource)
Arguments:
resource -- a g:resource instance
Details:
Unregisters the resource from the process-global set of resources.
See also:
2024-5-12
Function gio:resources-lookup-data (path &optional lookup)
Arguments:
path -- a string with a pathname inside the resource
lookup -- an optional g:resource-lookup-flags value, the default value is :none
Returns:
The pointer or cffi:null-pointer.
Details:
Looks for a file at the specified path in the set of globally registered resources and returns a pointer 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.

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.

The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21
Function gio:resources-enumerate-children (path lookup)
Arguments:
path -- a string with a pathname inside the resource
lookup -- a g:resource-lookup-flags value
Returns:
The list of strings.
Details:
Returns all the names of children at the specified path in the set of globally registered resources. The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21
Function gio:resources-info (path lookup)
Arguments:
path -- a string with a pathname inside the resource
lookup -- a g:resource-lookup-flags value
Returns:
size -- an integer with the length of the contents of the file
flags -- an unsigned integer with the flags about the file
Details:
Looks for a file at the specified path in the set of globally registered resources and if found returns information about it. The lookup argument controls the behaviour of the lookup.
See also:
2024-11-21

Permissions

GPermission

Class gio:permission
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
allowed
The allowed property of type :boolean (Read)
True if the caller currently has permission to perform the action that the g:permission object represents the permission to perform.
Default value: false
can-acquire
The can-acquire property of type :boolean (Read)
True if it is generally possible to acquire the permission by calling the g:permission-acquire function.
Default value: false
can-release
The can-release property of type :boolean (Read)
True if it is generally possible to release the permission by calling the g:permission-release function.
Default value: false
Slot Access Functions:
Details:
A g:permission object represents the status of the permission of the caller 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 g:permission object might represent the ability for the user to write to a gtk:settings object. This g: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.
See also:
2023-5-5
Accessor gio:permission-allowed (object)
Syntax:
(g:permission-allowed object) => allowed
Arguments:
object -- a g:permission object
allowed -- a boolean whether the caller currently has permission to perform the action
Details:
Accessor of the allowed slot of the g:permission class. The g:permission-allowed function gets the value of the property. This property is true if the caller currently has permission to perform the action that the g:permission object represents the permission to perform.
See also:
2023-5-5
Accessor gio:permission-can-acquire (object)
Syntax:
(g:permission-can-acquire object) => can-acquire
Arguments:
object -- a g:permission object
can-acquire -- a boolean whether it is generally possible to acquire the permission
Details:
Accessor of the can-acquire slot of the g:permission class. The g:permission-can-acquire function gets the value of the property. This property is true if it is generally possible to acquire the permission by calling the g:permission-acquire function.
See also:
2023-5-5
Accessor gio:permission-can-release (object)
Syntax:
(g:permission-can-release object) => can-release
Arguments:
object -- a g:permission object
can-release -- a boolean whether it is generally possible to release the permission
Details:
Accessor of the can-release slot of the g:permission class. The g:permission-can-release function gets the value of the property. This property is true if it is generally possible to release the permission by calling the g:permission-release function.
See also:
2023-5-5
Function gio:permission-acquire (permission &optional cancellable)
Arguments:
permission -- a g:permission instance
cancellable -- a GCanellable instance, or nil
Returns:
True if the permission was successfully acquired.
Details:
Attempts to acquire the permission represented by permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password.

You should check with the g:permission-can-acquire function before calling this function. If the permission is acquired then true is returned. Otherwise, false is returned.

This call is blocking, likely for a very long time, in the case that user interaction is required.
See also:
#2024-11-21
Function gio:permission-release (permission &optional cancellable)
Arguments:
permission -- a g:permission instance
cancellable -- a GCanellable instance, or nil
Returns:
True if the permission was successfully released.
Details:
Attempts to release the permission represented by permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the permission will be dropped immediately without further action.

You should check with the g:permission-can-release function 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 also:
#2024-11-21

GSimplePermission

Class gio:simple-permission
Superclasses:
gio:permission, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The g:simple-permission class is a trivial implementation of the g:permission class that represents a permission that is either always or never allowed. The value is given at construction and does not change. Calling request or release will result in errors.
See also:
2023-5-5
Function gio:simple-permission-new (allowed)
Arguments:
allowed -- a boolean whether the action is allowed
Returns:
The newly created g:simple-permission instance.
Details:
Creates a new g:permission instance that represents an action that is either always or never allowed.
See also:
2024-12-19

Data models

GListModel

Interface gio:list-model
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The g:list-model interface is an interface that represents a mutable list of g:object instances. 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 "notify" signal. Taken together with the "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 g:list-model implementation 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 g:list-model instance are of, or derived from, the same type. The g:list-model-item-type function 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. The g:list-model-n-items function returns the number of items in the list and the g:list-model-item function 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 the g:list-model-item function until it returns nil.

An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone.

On the other side, a consumer is expected only to hold references on objects that are currently "user visible", in order to facilitate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time.

This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns the thread-default main context in effect at the time that the model was created.
Signal Details:
The "items-changed" signal
lambda (model pos removed added)    :run-last      
model
The g:list-model instance that changed.
pos
The unsigned integer with the position at which model changed.
removed
The unsigned integer with the number of items removed.
added
The unsigned integer with the number of items added.
This signal is emitted whenever items were added to or removed from model. At pos, removed items were removed and added items were added in their place. Note: If removed is not equal added, the positions of all later items in the model change.
See also:
2025-3-24
VTable gio:list-model-vtable
Declaration:
(gobject:define-vtable ("GListModel" list-model)
  (:skip parent-instance (:struct gobject:type-interface))
  ;; Methods of the GListModel interface
  (get-item-type                               ; virtual function
     (gobject:type-t                           ; return type
       (model (gobject:object list-model))))   ; argument
  (get-n-items (:uint
                (model (gobject:object list-model))))
  (get-item (gobject:object
             (model (gobject:object list-model))
             (pos :uint))))  
Values:
get-item-type
Virtual function called by the g:list-model-item-type function. You must implement the g:list-model-get-item-type-impl method, when subclassing from the g:list-model interface.
get-n-items
Virtual function called by the g:list-model-n-items function. You must implement the g:list-model-get-n-items-impl method, when subclassing from the g:list-model interface.
get-item
Virtual function called by the g:list-model-item function. You must implement the g:list-model-get-item-impl method, when subclassing from the g:list-model interface.
Details:
The virtual function table for the g:list-model interface.
Examples:
Simple example of subclassing the g:list-model interface. The model is internally represented as a Lisp list.
;; Simple implementation which uses a Lisp list
(gobject:define-gobject-subclass "CLListStore" cl-list-store
  (:superclass g:object
   :export t
   :interfaces ("GListModel"))
  ((:cl list
        :initform '()
        :accessor cl-list-store-list)))

(defmethod gio:list-model-get-item-type-impl ((store cl-list-store)) (g:gtype "GAction"))

(defmethod gio:list-model-get-n-items-impl ((store cl-list-store)) (length (cl-list-store-list store)))

(defmethod gio:list-model-get-item-impl ((store cl-list-store) pos) (let ((item (nth pos (cl-list-store-list store)))) (when item ;; We must add a reference to the returned item (g:object-ref item))))
See also:
2025-3-24
Generic gio:list-model-get-item-type-impl (model)
Arguments:
model -- a g:object instance
Returns:
The g:type-t type ID for the items contained in model.
Details:
Method called from the g:list-model-item-type function for a subclass of the g:list-model interface. You must implement the method, when subclassing the interface.
See also:
2025-3-24
Generic gio:list-model-get-n-items-impl (model)
Arguments:
model -- a g:object instance
Returns:
The unsigned integer with the number of items in model.
Details:
Method called from the g:list-model-n-items function for a subclass of the g:list-model interface. You must implement the method, when subclassing the interface.
See also:
2025-3-24
Generic gio:list-model-get-item-impl (model pos)
Arguments:
model -- a g:object instance
pos -- an unsigned integer for the postion of the item to fetch
Returns:
The g:object instance at pos.
Details:
Method called from the g:list-model-item function for a subclass of the g:list-model interface. You must implement the method, when subclassing the interface.
Notes:
You must add a reference with the g:object-ref function to the returned item.
See also:
2025-3-24
Function gio:list-model-item-type (model)
Arguments:
model -- a g:list-model object
Returns:
The g:type-t type ID of the items contained in model.
Details:
Gets the type of the items in the list model. All items returned from the g:list-model-item-type function are of that type or a subtype, or are an implementation of that interface. The item type of a g:list-model object can not change during the life of the model.
See also:
2025-3-24
Function gio:list-model-n-items (model)
Arguments:
model -- a g:list-model object
Returns:
The integer with the number of items in model.
Details:
Gets the number of items in the list model. Depending on the list model implementation, calling this function may be less efficient than iterating the list model with increasing values for pos until the g:list-model-item functions returns the nil value.
See also:
2025-3-24
Function gio:list-model-item (model pos)
Arguments:
model -- a g:list-model object
pos -- an unsigned integer for the position of the item to fetch
Returns:
The g:object instance at pos.
Details:
Gets the item at pos. If the pos argument is greater than the number of items in the list model, nil is returned. The nil value is never returned for an index that is smaller than the length of the list model. See the g:list-model-n-items function.
See also:
2025-3-24
Function gio:list-model-items-changed (model pos removed added)
Arguments:
model -- a g:list-model object
pos -- an unsigned integer for the position at which model changed
removed -- an unsigned integer for the number of items removed
added -- an unsigned integer for the number of items added
Details:
Emits the "items-changed" signal on model. This function should only be called by classes implementing the g:list-model interface. It has to be called after the internal representation of the list model has been updated, because handlers connected to this signal might query the new state of the list model.

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 the g:list-store object, 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 g:list-model 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 main loop, and without calling other code, will continue to view the same contents of the model.
See also:
2025-3-24

GListStore

Class gio:list-store
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read / Write / Construct Only)
The type of items contained in the list store. Items must be subclasses of the g:object class.
n-items
The n-items property of type :uint (Read)
The number of items contained in the list store. Since 2.74
Default value: 0
Returned by:
Slot Access Functions:
Details:
The g:list-store object is an implementation of the g:list-model interface 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. Items must be subclasses of the g:object class.
See also:
2025-3-24
Accessor gio:list-store-item-type (object)
Syntax:
(g:list-store-item-type object) => gtype
Arguments:
object -- a g:list-store object
gtype -- a g:type-t type ID
Details:
Accessor of the item-type slot of the g:list-store class. The type of items contained in the list store. Items must be subclasses of the g:object class.
Notes:
This function is equivalent to the g:list-model-item-type function.
Examples:
(g:list-store-new "GAction")
=> #<GIO:LIST-STORE {1003FCA4C3}>
(g:list-store-item-type *)
=> #<GTYPE :name "GAction" :id 106084831684528>    
See also:
2025-3-24
Accessor gio:list-store-n-items (object)
Syntax:
(g:list-store-n-items object) => n-items
Arguments:
object -- a g:list-store object
n-items -- an unsigned integer with the number of items contained in the list store
Details:
Accessor of the n-items slot of the g:list-store class.
Notes:
This function is equivalent to the g:list-model-n-items function.


Since 2.74
See also:
2025-3-24
Function gio:list-store-new (gtype)
Arguments:
gtype -- a g:type-t type ID for the items in the list
Returns:
The new g:list-store object.
Details:
Creates a new list store with items of gtype type. The gtype type must be a subclass of the g:object class.
Examples:
Create a list store for g:app-info objects containing all applications registered on the system.
(defun create-application-list ()
  (let ((store (g:list-store-new "GAppInfo"))
        (apps (g:app-info-all)))
    (dolist (app apps)
      (g:list-store-append store app))
  store))    
See also:
2025-4-11
Function gio:list-store-append (store item)
Arguments:
store -- a g:list-store object
item -- a g:object object with the new item
Details:
Appends the item to the list store. The item must be of item-type type. Use the g:list-store-splice function to append multiple items at the same time efficiently.
See also:
2025-3-24
Function gio:list-store-insert (store pos item)
Arguments:
store -- a g:list-store object
pos -- an unsigned integer with the position at which to insert the new item
item -- a g:object instance for the new item
Details:
Inserts the item into the list store at pos. The item must be of item-type type or derived from it. The pos argument must be smaller than the length of the list store, or equal to it to append.

Use the g:list-store-splice function to insert multiple items at the same time efficiently.
See also:
2025-3-24
Callback gio:compare-data-func
Syntax:
lambda (a b) => result
Arguments:
a -- a g:object instance
b -- a g:object instance to compare with
result -- negative integer if a < b, zero if a = b, positive integer if a > b
Details:
Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.
See also:
2025-3-24
Function gio:list-store-insert-sorted (store item func)
Arguments:
store -- a g:list-store object
item -- a g:object object
func -- a g:compare-data-func callback function
Returns:
The unsigned integer with the position at which item was inserted.
Details:
Inserts the item into the list store at a position to be determined by the func callback function. The list store 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.
See also:
2025-3-24
Function gio:list-store-remove (store pos)
Arguments:
store -- a g:list-store object
pos -- an unsigned integer with the position of the item that is to be removed
Details:
Removes the item from the list store that is at pos. The pos argument must be smaller than the current length of the list store. Use the g:list-store-splice function to remove multiple items at the same time efficiently.
See also:
2025-3-24
Function gio:list-store-remove-all (store)
Arguments:
store -- a g:list-store object
Details:
Removes all items from the list store.
See also:
2025-3-24
Function gio:list-store-splice (store pos n &rest additions)
Arguments:
store -- a g:list-store object
pos -- an unsigned integer with the position at which to make the change
n -- an unsigned integer with the number of items to remove
additions -- g:object instances to add
Details:
Changes the list store by removing n items and adding additions to it. The additions values must contain items of the item-type type. This function is more efficient than the g:list-store-insert and g:list-store-remove functions, because it only emits the "items-changed" signal once for the change.

The pos and n arguments must be correct, that is, pos + n must be less than or equal to the length of the list store at the time this function is called.
See also:
2025-3-24
Function gio:list-store-sort (store func)
Arguments:
store -- a g:list-store object
func -- a g:compare-data-func callback function for sorting
Details:
Sort the items in the list store according to func.
See also:
2025-3-24
Function gio:list-store-find (store item)
Arguments:
store -- a g:list-store object
item -- a g:object item
Returns:
The unsigned integer with the first position of the item, if it was found, otherwise nil.
Details:
Looks up the given item in the list store by looping over the items until the first occurrence of item. If the item argument was not found, then this method will return nil.

If you need to compare the two items with a custom comparison function, use the g:list-store-find-with-equal-func function with a custom g:equal-func-full callback function instead.

Since 2.64
See also:
2025-3-24
Callback gio:equal-func-full
Syntax:
lambda (a b) => result
Arguments:
a -- a g:object instance
b -- a g:object instance to compare with
result -- true if a = b, false otherwise
Details:
Specifies the type of a callback function used to test two values for equality. The function should return true if both values are equal and false otherwise.

Since 2.74
See also:
2025-3-24
Function gio:list-store-find-with-equal-func (store item func)
Arguments:
store -- a g:list-store object
item -- a g:object object
func -- a g:equal-func-full callback function
Returns:
The unsigned integer with the first position of the item, if it was found, otherwise nil.
Details:
Looks up the given item in the list store by looping over the items and comparing them with the func callback function until the first occurrence of item which matches. If the item was not found, this method will return false.

Since 2.74
See also:
2025-3-24

Application support

GApplication

GFlags gio:application-flags
Declaration:
(gobject:define-gflags "GApplicationFlags" application-flags
  (:export t
   :type-initializer "g_application_flags_get_type")
  #-glib-2-74
  (:flags-none 0)
  #+glib-2-74
  (:default-flags 0)
  (:is-service 1)
  (:is-launcher 2)
  (:handles-open 4)
  (:handles-command-line 8)
  (:send-enviroment 16)
  (:non-unique 32)
  (:can-override-app-id 64)
  #+glib-2-60
  (:allow-replacement 128)
  #+glib-2-60
  (:replace 256))  
Values:
:flags-none
Default flags, deprecated since 2.74.
:default-flags
Default flags. Since 2.74
:is-service
Run as a service. In this mode, registration fails if the service is already running, and the application will initially wait up to 10 seconds for an initial activation message to arrive.
:is-launcher
Do not try to become the primary instance.
:handles-open
This application handles opening files in the primary instance. Note that this flag only affects the default implementation of the local_command_line() virtual function, and has no effect if the :handles-command-line flag is given. See the g:application-run function for details.
:handles-command-line
This application handles command line arguments in the primary instance. Note that this flag only affect the default implementation of the local_command_line() virtual function. See the g:application-run function for details.
:send-enviroment
Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the GIT_COMMITTER_NAME environment variable when editing a GIT commit message. The environment is available to the "command-line" signal handler via the g:application-command-line-getenv function.
:non-unique
Make no attempts to do any of the typical single-instance application negotiation. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process.
:can-override-app-id
Allow users to override the application ID from the command line with the --gapplication-app-id option.
:allow-replacement
Allow another instance to take over the bus name. Since 2.60
:replace
Take over from another instance. This flag is usually set by passing the --gapplication-replace option on the command line. Since 2.60
Details:
Flags used to define the behaviour of a g:application instance.
See also:
2025-2-3
Class gio:application
Superclasses:
gio:action-group, gio:action-map, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
action-group
The action-group property of type g:action-group (Write)
The group of actions that the application exports.
Warning: Deprecated since version 2.32. Use the g:action-map interface instead.
application-id
The application-id property of type :string (Read / Write / Construct)
The unique identifier for the application.
Default value: nil
flags
The flags property of type g:application-flags (Read / Write)
Flags specifying the behaviour of the application.
Default value: '()
inactivity-timeout
The inactivity-timeout property of type :uint (Read / Write)
Time in milliseconds to stay alive after becoming idle.
Default value: 0
is-busy
The is-busy property of type :boolean (Read)
Whether the application is currently marked as busy.
Default value: false
is-registered
The is-registered property of type :boolean (Read)
Whether the application is registered.
Default value: false
is-remote
The is-remote property of type :boolean (Read)
Whether the application is remote.
Default value: false
resource-base-path
The resource-base-path property of type :string (Read / Write)
The base resource path for the application.
Default value: nil
version
The version property of type :string (Read / Write)
The human-readable version number of the application. Since 2.80
Default value: nil
Returned by:
Slot Access Functions:
Details:
The g:application class is the foundation of an application. The g:application class wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as the gtk:application class. In general, you should not use this class outside of a higher level framework.

The g:application class provides convenient life cycle management by maintaining a "use count" for the primary application instance. The use count can be changed using the g:application-hold and g:application-release functions. If it drops to zero, the application exits. Higher-level classes such as the gtk:application class employ the use count to ensure that the application stays alive as long as it has any opened windows.

Another feature that the g:application class, optionally, provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session concept is platform dependent, but corresponds roughly to a graphical desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the "primary instance". For non-unique applications this is always the current instance. On Linux, the D-Bus session bus is used for communication.

The use of the g:application class differs from some other commonly used uniqueness libraries, such as the libunique library, 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 g:application instance should do very little more than instantiating the application instance, possibly connecting signal handlers, then calling the g:application-run function. All checks for uniqueness are done internally. If the application is the primary instance then the "startup" signal is emitted and the main loop runs. If the application is not the primary instance then a signal is sent to the primary instance and the g:application-run function promptly returns.

If used, the expected form of an application identifier is the same as that of of a D-Bus well-known bus name. Examples include: "com.example.MyApp", "org.example.apps.Calculator", "org._7_zip.Archiver". For details on valid application identifiers, see the g:application-id-is-valid function.

On Linux, the application identifier is claimed as a well-known bus name on the session bus of the user. This means that the uniqueness of the application is scoped to the current session. It also means that the 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 a g:application instance attempts to acquire the bus name of your application, which happens in the g:application-register function. Unfortunately, this means that you cannot use the g:application-is-remote function to decide if you want to register object paths.

The g:application class also implements the g:action-group and g:action-map interfaces and lets you easily export actions by adding them with the g:action-map-add-action function. When invoking an action by calling the g:action-group-activate-action function on the application, it is always invoked in the primary instance. The actions are also exported on the session bus, and GIO provides the GDBusActionGroup wrapper to conveniently access them remotely. GIO provides a GDBusMenuModel wrapper for remote access to exported g:menu-model objects.

There is a number of different entry points into a g:application instance:
  • via 'Activate', that is just starting the application
  • via 'Open', that is opening some files
  • by handling a command-line
  • via activating an action
The "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, the g:application instance passes some platform data from the launching instance to the primary instance, in the form of a g:variant dictionary mapping strings to variants. To use platform data, override the before_emit() or after_emit() virtual functions in your g:application subclass. When dealing with g:application-command-line objects, the platform data is directly available via the g:application-command-line-cwd, g:application-command-line-environ and g:application-command-line-platform-data functions.

As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory, "cwd" key, and optionally the environment, that is, the set of environment variables and their values, of the calling process, "environ" key. The environment is only added to the platform data if the :send-enviroment flag is set. A g:application subclass can add own platform data by overriding the add_platform_data() virtual function. For instance, the gtk:application class adds startup notification data in this way.

To parse command line arguments you may handle the "command-line" signal or override the local_command_line() virtual function, to parse them in either the primary instance or the local instance, respectively.
Examples:
An example to show the use of the signals of an application.
(defun application-open (&rest argv)
  (let ((app (make-instance 'g:application
                            :application-id "com.crategus.application-open"
                            :flags :handles-open))
        (argv (or argv (uiop:command-line-arguments))))
    ;; Print information about the application
    (format t "Start application~%")
    (format t "      arg : ~a~%" argv)
    (format t "  prgname : ~a~%" (g:prgname))
    ;; Signal handler "startup"
    (g:signal-connect app "startup"
                      (lambda (application)
                        (declare (ignore application))
                        (format t "The application is in STARTUP~%")))
    ;; Signal handler "activate"
    (g:signal-connect app "activate"
                      (lambda (application)
                        (declare (ignore application))
                        (format t "The application is in ACTIVATE~%")
                        ;; Note: when doing a longer-lasting action here that
                        ;; returns to the main loop, you should use
                        ;; g:application-hold and g:application-release to
                        ;; keep the application alive until the action is
                        ;; completed.
                      ))
    ;; Signal handler "open"
    (g:signal-connect app "open"
                      (lambda (application files nfiles hint)
                        (declare (ignore application))
                          (format t "The application is in OPEN~%")
                          (format t "  nfiles : ~A~%" nfiles)
                          (format t "     hint : ~A~%" hint)
                          ;; The argument FILES is a C pointer to an array of
                          ;; GFile objects. We list the pathnames of the files.
                          (dotimes (i nfiles)
                            (let ((file (mem-aref files '(g:object g:file) i)))
                              (format t " ~a~%" (g:file-path file))))))
    ;; Signal handler "shutdown"
    (g:signal-connect app "shutdown"
                      (lambda (application)
                        (declare (ignore application))
                        (format t "The application is in SHUTDOWN~%")))
    ;; Run the application
    (g:application-run app argv)))    
An example to show the implementation of actions for an application.
(defun activate-action (app name)
  (let ((ptype (g:action-group-action-parameter-type app name))
        (state (g:action-group-action-state app name))
        (enabled (g:action-group-action-enabled app name)))
    ;; Print information about the action
    (format t "     action name : ~A~%" name)
    (format t "  parameter type : ~A~%" ptype)
    (unless (null-pointer-p state)
      (format t "      state type : ~A~%" (g:variant-type-string state)))
    (format t "           state : ~A~%" state)
    (format t "         enabled : ~A~%" enabled)
    ;; Activate the action
    (g:action-group-activate-action app name state)))

(defun application-action (&rest argv) (let ((app (make-instance 'g:application :application-id "com.crategus.application-action" :flags :none))) ;; Create the "simple-action" action (let ((action (g:simple-action-new "simple-action" nil))) ;; Connect a handler to the "activate" signal (g:signal-connect action "activate" (lambda (action parameter) (declare (ignore parameter)) (format t "Action ~A is activated.~%" (g:action-name action)))) ;; Add the action to the action map of the application (g:action-map-add-action app action)) ;; Create the "toggle-action" action (let ((action (g:simple-action-new-stateful "toggle-action" "b" (g:variant-new-boolean nil)))) ;; Connect a handler to the "activate" signal (g:signal-connect action "activate" (lambda (action parameter) (declare (ignore parameter)) (format t "Action ~A is activated.~%" (g:action-name action)) (let ((state (g:variant-boolean (g:action-state action)))) (if state (setf (g:action-state action) (g:variant-new-boolean nil)) (setf (g:action-state action) (g:variant-new-boolean t))) (format t "The state changed from ~A to ~A.~%" state (not state))))) ;; Add the action to the action map of the application (g:action-map-add-action app action)) ;; Signal handler "activate" (g:signal-connect app "activate" (lambda (application) (format t "The application is in activate.~%") ;; Activate the actions and print information (activate-action application "simple-action") (activate-action application "toggle-action"))) ;; Run the application (g:application-run app argv)))
Signal Details:
The "activate" signal
lambda (application)    :run-last      
application
The g:application instance which received the signal.
The signal is emitted on the primary instance when an activation occurs. See the g:application-activate function.
The "command-line" signal
lambda (application cmdline)    :run-last      
application
The g:application instance which received the signal.
cmdline
The g:application-command-line instance representing the passed command line.
Returns
The integer that is set as the exit status for the calling process.
The signal is emitted on the primary instance when a command line is not handled locally. See the g:application-run function and the g:application-command-line documentation for more information.
The "handle-local-options" signal
lambda (application options)    :run-last      
application
The g:application instance which received the signal.
options
The options dictionary of g:variant-dict type.
Returns
The 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. Return -1 to let the default option processing continue.
The signal is emitted on the local instance after the parsing of the command line options has occurred. You can add options to be recognised during command line option parsing using the g:application-add-main-option-entries and g:application-add-option-group functions.

Signal handlers can inspect options, along with values pointed to from the arg-data field of an installed option entry, 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 with the :handles-command-line flag the "normal processing" will send the options dictionary to the primary instance where it can be read with the g:application-command-line-options-dict function. The signal handler can modify the dictionary before returning, and the modified dictionary will be sent.

In the event that the :handles-command-line flag 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 the g:application-activate function. One or more arguments results in a call to the g:application-open function.

If you want to handle the local command line arguments for yourself by converting them to calls to the g:application-open or g:action-group-activate-action functions then you must be sure to register the application first. You should probably not call the g:application-activate function 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, that is no activation in that case.

Note that this signal is emitted from the default implementation of the local_command_line() virtual function. If you override that function and do not chain up then this signal will never be emitted. You can override the local_command_line() virtual function if you need more powerful capabilities than what is provided here, but this should not normally be required.
The "name-lost" signal
lambda (application)    :run-last      
application
The g:application instance which received the signal.
Returns
True if the signal has been handled.
The signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the :allow-replacement flag. The default handler for this signal calls the g:application-quit function. Since 2.60.
The "open" signal
lambda (application files nfiles hint)    :run-last      
application
The g:application instance which received the signal.
files
The C array of g:file objects.
nfiles
The integer with the length of files.
hint
The string with a hint provided by the calling instance.
The signal is emitted on the primary instance when there are files to open. See the g:application-open function for more information.
The "shutdown" signal
lambda (application)    :run-last      
application
The g:application instance which received the signal.
The signal is emitted only on the registered primary instance immediately after the main loop terminates.
The "startup" signal
lambda (application)    :run-first      
application
The g:application instance which received the signal.
The signal is emitted on the primary instance immediately after registration. See the g:application-register function.
See also:
2025-2-3
Accessor gio:application-action-group (object)
Syntax:
(setf (g:application-action-group object) group)
Arguments:
object -- a g:application instance
group -- a g:action-group instance, or nil
Details:
Accessor of the action-group slot of the g:application class. This used to be how actions were associated with a g:application instance. Now there is the g:action-map interface for that.
Warning:
The g:application-action-group function has been deprecated since version 2.32 and should not be used in newly written code. Use the g:action-map interface instead. Never ever mix use of this API with use of the g:action-map interface on the same application or things will go very badly wrong. This function is known to introduce buggy behaviour, that is, signals not emitted on changes to the action group.
See also:
2025-2-3
Accessor gio:application-application-id (object)
Syntax:
(g:application-application-id object) => id
(setf (g:application-application-id object) id)
Arguments:
object -- a g:application instance
id -- a string with the identifier of the application
Details:
Accessor of the application-id slot of the g:application class. The g:application-application-id function gets the unique identifier for the application. The (setf g:application-application-id) function sets the unique identifier.

The application ID can only be modified if the application has not yet been registered. The application ID must be valid. See the g:application-id-is-valid function.
See also:
2025-2-3
Accessor gio:application-flags (object)
Syntax:
(g:application-flags object) => flags
(setf (g:application-flags object) flags)
Arguments:
object -- a g:application instance
flags -- a g:application-flags value for the application
Details:
Accessor of the flags slot of the g:application class. The g:application-flags function gets the flags for the application. The (setf g:application-flags) function sets the flags.

The flags can only be modified if the application has not yet been registered. See the g:application-flags documentation.
See also:
2025-2-3
Accessor gio:application-inactivity-timeout (object)
Syntax:
(g:application-inactivity-timeout object) => timeout
(setf (g:application-inactivity-timeout object) timeout)
Arguments:
object -- a g:application instance
timeout -- an unsigned integer with the timeout in milliseconds
Details:
Accessor of the inactivity-timeout slot of the g:application class. The g:application-inactivity-timeout function gets the current inactivity timeout for the application. The (setf g:application-inactivity-timeout) function sets the inactivity timeout.

This is the amount of time in milliseconds after the last call to the g:application-release function before the application stops running. This call has no side effects of its own. The value set here is only used for next time the g:application-release function drops the use count to zero. Any timeouts currently in progress are not impacted.
See also:
2025-2-3
Accessor gio:application-is-busy (object)
Syntax:
(g:application-is-busy object) => setting
Arguments:
object -- a g:application instance
setting -- true if the application is currenty marked as busy
Details:
Accessor of the is-busy slot of the g:application class. Gets the current busy state of the application, as set through the g:application-mark-busy or g:application-bind-busy-property functions.
See also:
2025-2-3
Accessor gio:application-is-registered (object)
Syntax:
(g:application-is-registered object) => setting
Arguments:
object -- a g:application instance
setting -- true if the application is registered
Details:
Accessor of the is-registered slot of the g:application class. Checks if the application is registered. An application is registered if the g:application-register function has been successfully called.
See also:
2025-2-3
Accessor gio:application-is-remote (object)
Syntax:
(g:application-is-remote object) => setting
Arguments:
object -- a g:application instance
setting -- true if the application is remote
Details:
Accessor of the is-remote slot of the g:application class. Checks if the application is remote. If the application is remote then it means that another instance of the application already exists, the 'primary' instance. Calls to perform actions on the application will result in the actions being performed by the primary instance. The value of this property cannot be accessed before the g:application-register function has been called. See the g:application-is-registered function.
See also:
2025-2-3
Accessor gio:application-resource-base-path (object)
Syntax:
(g:application-resource-base-path object) => path
(setf (g:application-resource-base-path object) path)
Arguments:
object -- a g:application instance
path -- a string with the resource base path to use
Details:
Accessor of the resource-base-path slot of the g:application class. The g:application-resource-base-path function gets the resource base path of the application. The (setf g:application-resource-base-path) function sets or unsets the resource base path.

The resource base path is used to automatically load various application resources such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given resource 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 g:application instance 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 gtk:application instance, and you have not manually changed the resource base path, then GTK will then search for the menus of the application at "/org/example/app/gtk/menus.ui". See the g:resource documentation for more information about adding resources to your application. You can disable automatic resource loading functionality by setting the resource base path to nil.

Changing the resource base path once the application is running is not recommended. The point at which the resource base path is consulted for forming paths for various purposes is unspecified. When writing a subclass of the g:application class you should either set the resource-base-path property at construction time, or call this function during the instance initialization.
See also:
2025-2-3
Accessor gio:application-version (object)
Syntax:
(g:application-version object) => version
(setf (g:application-version object) version)
Arguments:
object -- a g:application instance
version -- a string with the version number of the application
Details:
Accessor of the version slot of the g:application class. The g:application-version function gets the version of the application. The (setf g:application-version) function sets the version. This will be used to implement a --version command line argument. The application version can only be modified if the application has not yet been registered.

Since 2.80
See also:
2025-2-3
Function gio:application-id-is-valid (id)
Arguments:
id -- a string for a potential application identifier
Returns:
True if id is a valid application ID.
Details:
Checks if the id argument is a valid application identifier. A valid application ID is required for calls to the g:application-new and g:application-application-id functions.

The restrictions on application identifiers are:
  • Application identifiers must contain only the ASCII characters "[A-Z] [a-z] [0-9] _ - ." and must not begin with a digit.
  • Application identifiers must contain at least one '.' period character and thus at least three elements.
  • Application identifiers must not begin or end with a '.' period character.
  • Application identifiers must not contain consecutive '.' period characters.
  • Application identifiers must not exceed 255 characters.
Examples:
(g:application-id-is-valid "com.crategus.application") => T
(g:application-id-is-valid "application") => NIL    
See also:
2025-2-3
Function gio:application-new (id flags)
Arguments:
id -- a string with the application ID
flags -- a g:application-flags value
Returns:
The new g:application instance.
Details:
Creates a new g:application instance. The application ID must be valid. See the g:application-id-is-valid function.
See also:
#2025-2-3
Function gio:application-register (application)
Arguments:
application -- a g:application instance
Returns:
True if registration succeeded.
Details:
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.

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 "startup" signal is emitted if registration succeeds and the application is the primary instance. In the event of an error false is returned.
Notes:
The return value of this function is not an indicator that this instance is or is not the primary instance of the application. See the g:application-is-remote function for that.
See also:
#2025-2-3
Function gio:application-hold (application)
Arguments:
application -- a g:application instance
Details:
Increases the use count of the application. Use this function to indicate that the application has a reason to continue to run. For example, the function is called by GTK when a toplevel window is on the screen. To cancel the hold, call the g:application-release function.
See also:
2025-2-3
Function gio:application-release (application)
Arguments:
application -- a g:application instance
Details:
Decrease the use count of the application. When the use count reaches zero, the application will stop running. Never call this function except to cancel the effect of a previous call to the g:application-hold function.
See also:
2025-2-3
Function gio:application-quit (application)
Arguments:
application -- a g:application instance
Details:
Immediately quits the application. Upon return to the main loop, the g:application-run function will return, emitting only the "shutdown" signal before doing so. The hold count is ignored. The result of calling the g:application-run function again after it returns is unspecified.
See also:
#2025-2-3
Function gio:application-activate (application)
Arguments:
application -- a g:application instance
Details:
Activates the application. In essence, this results in the "activate" signal being emitted in the primary instance. The application must be registered before calling this function.
See also:
2025-2-3
Function gio:application-open (application files &optional hint)
Arguments:
application -- a g:application instance
files -- a list of strings for the file names
hint -- an optional string for a hint or the default empty string ""
Details:
This results in the "open" signal being emitted in the primary instance. The hint argument is simply passed through to the "open" signal. It is intended to be used by applications that have multiple modes for opening files, for example, "view" versus "edit". Unless you have a need for this functionality, you should use an empty string "".

The application must be registered before calling this function and it must have the :handles-open flag set.
See also:
2025-2-3
Function gio:application-run (application argv)
Arguments:
application -- a g:application instance
argv -- a list of strings with command line parameters, or nil
Returns:
The integer with the exit status.
Details:
Runs the application. This function is intended to be run from the main function and its return value is intended to be returned by the main function. Although you are expected to pass the argv parameters from the main function to this function, it is possible to pass no arguments, if the command line arguments are not available or command line handling is not required. Note that on Windows, the command line arguments are ignored, and the g_win32_get_command_line() function is called internally, for proper support of Unicode command line arguments.

The g:application instance will attempt to parse the command line arguments. You can add command line flags to the list of recognised options by way of the g:application-add-main-option-entries function. After this, the "handle-local-options" signal is emitted, from which the application can inspect the values of its option entries.

The "handle-local-options" signal handler 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 "handle-local-options" signal 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 g:application-flags flags: if the :handles-command-line flag was specified then the remaining command line arguments are sent to the primary instance, where a "command-line" signal is emitted. Otherwise, the remaining command line arguments are assumed to be a list of files. If there are no files listed, the application is activated via the "activate" signal. If there are one or more files, and the :handles-open flag was specified then the files are opened via the "open" signal.

If you are interested in doing more complicated local handling of the command line then you should implement your own g:application subclass and override the local_command_line() virtual function. In this case, you most likely want to return true from your local_command_line() implementation to suppress the default handling.

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 :is-service flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that the g:application-inactivity-timeout function is in use.

This function sets the program name with the g:prgname function, if not already set, to the basename of the first value of the command line arguments.

Much like the g:main-loop-run function, this function will acquire the main context for the duration that the application is running.

Applications that are not explicitly flagged as services or launchers, that is, neither the :is-service or the :is-launcher values are given as flags, will check, from the default handler for the local_command_line() virtual function, if the --gapplication-service option was given in the command line. If this flag is present then normal command line processing is interrupted and the :is-service flag is set. This provides a "compromise" solution whereby running an application directly from the command line 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 the --gapplication-service option as the sole command line 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 command line will exit and what their exit status will be.
See also:
2025-2-3
Function gio:application-send-notification (application id notification)
Arguments:
application -- a g:application instance
id -- a string for the ID of the notification, or nil
notification -- a g:notification instance to send
Details:
Sends a notification on behalf of the application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all. Notifications may persist after the application exits. It will be D-Bus activated when the notification or one of its actions is activated. Modifying notification after this call has no effect. However, the object can be reused for a later call to this function. The id argument 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. The id argument may be nil, but it is impossible to replace or withdraw notifications without an ID.

If the notification is no longer relevant, it can be withdrawn with the g:application-withdraw-notification function.
See also:
#2025-2-3
Function gio:application-withdraw-notification (application id)
Arguments:
application -- a g:application instance
id -- a string for the ID of a previously sent notification
Details:
Withdraws a notification that was sent with the g:application-send-notification function. This call does nothing if a notification with id does not 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.
See also:
#2025-2-3
Function gio:application-add-main-option-entries (application entries)
Arguments:
application -- a g:application instance
entries -- a list of option entries, see the g:option-context-add-main-entries function for a documentation of option entries
Details:
Adds main option entries to be handled by the application. After the command line arguments are parsed, the "handle-local-options" signal will be emitted. At this point, the application can inspect the values pointed to by the arg-data field in the given option entries.

Unlike the g:option-context implementation, the g:application class supports giving nil for the arg-data field for a non-callback option entry. This results in the argument in question being packed into a g:variant-dict parameter which is also passed to the "handle-local-options" signal handler, where it can be inspected and modified. If the :handles-command-line flag is set, then the resulting dictionary is sent to the primary instance, where the g:application-command-line-options-dict function will return it. This "packing" is done according to the type of the argument - booleans for normal flags, strings for strings, bytestrings for filenames, and so on. The packing only occurs if the flag is given, that is, we do not pack a g:variant parameter in the case that a flag is missing.

In general, it is recommended that all command line arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where the g:variant-dict-lookup function can be used. For local options, it is possible to either use the arg-data field 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 command line arguments, options and all, to the primary instance for handling. The g:application instance 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 the :handles-command-line flag is unset.

If the "handle-local-options" signal needs to see the list of filenames, then the use of G_OPTION_REMAINING is recommended. If the arg-data field is nil 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 g:variant parameter format when retrieving the options with the g:variant-dict-lookup function:
  • for :none, use "b"
  • for :string, use "&s"
  • for :int, use "i"
  • for :int64, use "x"
  • for :double, use "d"
  • for :filename, use "^ay"
  • for :string-array, use "&as"
  • for :filename-array, use "^aay"
See also:
2025-2-3
Function gio:application-add-main-option (application long short flags arg desc argdesc)
Arguments:
application -- a g:application instance
long -- a string for the long name of an option used to specify it in a command line
short -- a printable ASCII g:unichar character for the short name of an option
flags -- a g:option-flags value for the flags
arg -- a g:option-arg value for the type of the option
desc -- a string for the description for the option in --help output
argdesc -- a string for the placeholder to use for the extra argument parsed by the option in --help output
Details:
Adds an option to be handled by the application. Calling this function is the equivalent of calling the g:application-add-main-option-entries function with a single option entry that has its the arg-data field set to nil.

The parsed arguments will be packed into a g:variant-dict parameter which is passed to the "handle-local-options" signal handler. If the :handles-command-line flag is set, then it will also be sent to the primary instance. See the g:application-add-main-option-entries function for more details.

See the g:option-group-add-entries function for more documentation of the arguments.
See also:
2025-2-3
Function gio:application-add-option-group (application group)
Arguments:
application -- a g:application instance
group -- a g:option-group instance
Details:
Adds a g:option-group instance to the command line handling of the application. This function is comparable to the g:option-context-add-group function.

Unlike the g:application-add-main-option-entries function, this function does not deal with nil for the arg-data field 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 "command-line" signal 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 the g:option-group instance 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 the :handles-command-line flag was given.
See also:
#2025-2-3
Function gio:application-set-option-context-parameter-string (application parameter)
Arguments:
application -- a g:application instance
parameter -- a string which is displayed in the first line of --help output
Details:
Sets the parameter string to be used by the command line handling of the application. This function registers the argument to be passed to the g:option-context-new function when the internal g:option-context instance of the application is created.

See the g:option-context-new function for more information about the parameter argument.
See also:
#2025-2-3
Function gio:application-set-option-context-summary (application summary)
Arguments:
application -- a g:application instance
summary -- a string to be shown in --help output before the list of options, or nil
Details:
Adds a summary to the application option context. See the g:option-context-summary function for more information.
See also:
#2025-2-3
Function gio:application-set-option-context-description (application description)
Arguments:
application -- a g:application instance
description -- a string to be shown in --help output after the list of options, or nil
Details:
Adds a description to the application option context. See the g:option-context-description function for more information.
See also:
#2025-2-3
Function gio:application-default ()
Syntax:
(g:application-default) => application
(setf (g:application-default) application)
Arguments:
application -- a g:application instance to set as default, or nil
Details:
Accessor of the default application for the process. The g:application-default function returns the default application instance for this process. The (setf g:application-default) function sets or unsets the default application.

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 this function.

If there is no default application then nil is returned.
See also:
#2025-2-3
Function gio:application-mark-busy (application)
Arguments:
application -- a g:application instance
Details:
Increases the busy count of the application. Use this function to indicate that the application is busy, for instance while a long running operation is pending. The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user, for example, with a spinner. To cancel the busy indication, use the g:application-unmark-busy function.
See also:
#2025-2-3
Function gio:application-unmark-busy (application)
Arguments:
application -- a g:application instance
Details:
Decreases the busy count of the application. When the busy count reaches zero, the new state will be propagated to other processes. This function must only be called to cancel the effect of a previous call to the g:application-mark-busy function.
See also:
#2025-2-3
Function gio:application-bind-busy-property (application object property)
Arguments:
application -- a g:application instance
object -- a g:object instance
property -- a string for the name of a boolean property of object
Details:
Marks the application as busy while the property on the object is true. See the g:application-mark-busy function. The binding holds a reference to the application while it is active, but not to the object. Instead, the binding is destroyed when the object is finalized.
See also:
#2025-2-3
Function gio:application-unbind-busy-property (application object property)
Arguments:
application -- a g:application instance
object -- a g:object instance
property -- a string for the name of a boolean property of object
Details:
Destroys a binding between the property and the busy state of the application that was previously created with the g:application-bind-busy-property function.
See also:
#2025-2-3

GApplicationCommandLine

Class gio:application-command-line
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
arguments
The arguments property of type g:variant (Write / Construct Only)
The command line that caused the "command-line" signal emission.
Note: This property is not directly accessible from the Lisp side, but through the corresponding g:application-command-line-arguments function.
is-remote
The is-remote property of type :boolean (Read)
True if this is a remote command line.
Default value: false
options
The options property of type g:variant (Write / Construct Only)
The options sent along with the command line.
Note: This property is not directly accessible from the Lisp side, but through the corresponding g:application-command-line-options-dict function.
platform-data
The platform-data property of type g:variant (Write / Construct Only)
Platform-specific data for the command line.
Note: This property is not directly accessible from the Lisp side, but through the corresponding g:application-command-line-platform-data function.
Slot Access Functions:
Details:
The g:application-command-line class represents a command line invocation of an application. It is created by the g:application instance and emitted in the "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 command line invocation was local, that is, the current process is running in direct response to the invocation, or remote, that is, some other process forwarded the command line to this process.

The g:application-command-line instance can provide the command line arguments for use with the g:option-context command line parsing API, with the g:application-command-line-arguments function.

The exit status of the originally invoked process may be set and messages can be printed to stdout or stderr of that process. The life cycle of the originally invoked process is tied to the life cycle of this object, that is, the process exits when the last reference is dropped.

The main use for the g:application-command-line instance, and the "command-line" signal, is 'Emacs server' like use cases. You can set the EDITOR environment variable to have, for example 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.
Examples:
Normally, the command line is completely handled in the "command-line" signal 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.
(defun application-cmdline (&rest argv)
  (let ((app (make-instance 'g:application
                            :application-id
                            "com.crategus.application-cmdline"
                            :flags :handles-command-line))
        (argv (or argv (uiop:command-line-arguments))))
    ;; Print info about the application
    (format t "Start application~%")
    (format t "       argv : ~a~%" argv)
    (format t "    prgname : ~a~%" (g:prgname))
    ;; Signal handler "command-line"
    (g:signal-connect app "command-line"
        (lambda (application cmdline)
          (declare (ignore application))
          (let ((args (g:application-command-line-arguments cmdline)))
            (format t "Signal handler COMMAND-LINE~%")
            (format t "  arguments : ~a~%" args)
            ;; Return the exit status
            0)))
    ;; Run the application
    (g:application-run app argv)))    
This is the output, when executing the example from the Lisp prompt:
(gio-example:application-cmdline "file1" "file2")
=> Start application
        argv : (file1 file2)
     prgname : sbcl
   Signal handler COMMAND-LINE
         arguments : (file1 file2)
   0    
A stand-alone executable for the example has the following output:
./application-cmdline file1 file2
=> Start application
          argv : (file1 file2)
       prgname : application-cmdline
   Signal handler COMMAND-LINE
     arguments : (file1 file2)    
See also:
2025-2-3
Accessor gio:application-command-line-is-remote (object)
Arguments:
object -- a g:application-command-line instance
Returns:
True if the invocation was remote.
Details:
Determines if the command line represents a remote invocation.
See also:
#2024-12-27
Function gio:application-command-line-arguments (cmdline)
Arguments:
cmdline -- a g:application-command-line instance
Returns:
The list of strings containing the command line arguments.
Details:
Gets the list of arguments that was passed on the command line. The strings in the list 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 the g:option-context implementation, you must use the g:option-context-parse-strv function.
See also:
2025-2-3
Function gio:application-command-line-cwd (cmdline)
Arguments:
cmdline -- a g:application-command-line instance
Returns:
The string with the current directory, or nil.
Details:
Gets the working directory of the command line invocation. The string may contain non UTF-8 data.

It is possible that the remote application did not send a working directory, so this may be nil.
Examples:
(defvar cmd (make-instance 'g:application-command-line)) => CMD
(g:application-command-line-cwd cmd) => "/home/dieter/Lisp/lisp-projects"    
See also:
2025-2-3
Function gio:application-command-line-environ (cmdline)
Arguments:
cmdline -- a g:application-command-line instance
Returns:
The list of strings with the environment strings, or nil if they were not sent.
Details:
Gets the contents of the environ variable of the command line invocation, as would be returned by the g_get_environ() function. Each item in the list is of the form NAME = VALUE. The strings may contain non UTF-8 data.

The remote application usually does not send an environment. Use the :send-enviroment flag 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.

See the g:application-command-line-getenv function if you are only interested in the value of a single environment variable.
See also:
2025-2-3
Function gio:application-command-line-options-dict (cmdline)
Arguments:
cmdline -- a g:application-command-line instance
Returns:
The g:variant-dict instance with the options.
Details:
Gets the options that were passed to the g:application-command-line instance. If you did not override the local_command_line() virtual function then these are the same options that were parsed according to the options entries added to the application with the g:application-add-main-option-entries function and possibly modified from your "handle-local-options" signal handler.

If no options were sent then an empty dictionary is returned so that you do not need to check for nil.
See also:
#2025-2-3
Function gio:application-command-line-create-file-for-arg (cmdline arg)
Arguments:
cmdline -- a g:application-command-line instance
arg -- a string for an argument from cmdline
Returns:
The new g:file object.
Details:
Creates a g:file object corresponding to a filename that was given as part of the invocation of the command line. This differs from the g:file-new-for-commandline-arg function in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process.
See also:
#2025-2-3
Function gio:application-command-line-getenv (cmdline name)
Arguments:
cmdline -- a g:application-command-line instance
name -- a string for the environment variable to get
Returns:
The string with the value of the variable, or nil if unset or unsent.
Details:
Gets the value of a particular environment variable of the command line invocation, as would be returned by the g_getenv() function. The strings may contain non UTF-8 data.

The remote application usually does not send an environment. Use the :send-enviroment flag 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.
Examples:
(defvar cmd (make-instance 'g:application-command-line)) => CMD
(g:application-command-line-getenv cmd "HOME") => "/home/dieter"
(g:application-command-line-getenv cmd "unkown") => NIL    
See also:
#2025-2-3
Function gio:application-command-line-platform-data (cmdline)
Arguments:
cmdline -- a g:application-command-line instance
Returns:
The g:variant dictionary with the platform data, or a cffi:null-pointer value.
Details:
Gets the platform data associated with the invocation of cmdline. This is a g: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 a cffi:null-pointer value.
See also:
2025-2-3
Function gio:application-command-line-exit-status (cmdline)
Syntax:
(application-command-line-exit-status cmdline) => status
(setf (application-command-line-exit-status cmdline) status)
Arguments:
cmdline -- a g:application-command-line instance
status -- an integer with the exit status
Details:
Accessor of the exit status of a g:application-command-line instance. The g:application-command-line-exit-status function gets the exit status of cmdline. The (setf g:application-command-line-exit-status) function sets the exit status that will be used when the invoking process exits.

The return value of the "command-line" signal is passed to this function when the handler returns. This is the usual way of setting the exit status.

In the event that you want the remote invocation to continue running and want to decide on the exit status in the future, you can use this call. For the case of a remote invocation, the remote process will typically exit when the last reference is dropped on cmdline. The exit status of the remote process will be equal to the last value that was set with this function.

In the case that the command line invocation is local, the situation is slightly more complicated. If the command line invocation results in the main loop running, that is, 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 g:application-command-line instance is used.
See also:
#2025-2-3

GActionGroup

Interface gio:action-group
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The g:action-group interface 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 g:menu-model object that provides additional representation data for displaying the actions to the user, for example in a menu.

The main way to interact with the actions in a g:action-group instance is to activate them with the g:action-group-activate-action function. Activating an action may require a g:variant parameter. The required type of the parameter can be inquired with the g:action-group-action-parameter-type function. Actions may be disabled, see the g:action-group-action-enabled function. Activating a disabled action has no effect.

Actions may optionally have a state in the form of a g:variant parameter. The current state of an action can be inquired with the g:action-group-action-state function. Activating a stateful action may change its state, but it is also possible to set the state by calling the g:action-group-change-action-state function.

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 the g:action-group-list-actions function take the name of an action as an argument.

The g:action-group API is meant to be the 'public' API to the action group. The calls here are exactly the interaction that 'external forces', for example UI, incoming D-Bus messages, and so on, are supposed to have with actions. 'Internal' APIs, that is, ones meant only to be accessed by the action group implementation, are found on subclasses. This is why you will find, for example, the g:action-group-action-enabled function but not an equivalent setter function.

Signals are emitted on the action group in response to state changes on individual actions.

Implementations of the g:action-group interface should provide implementations for the g:action-group-list-actions and g:action-group-query-action virtual functions. The other virtual functions should not be implemented - their "wrappers" are actually implemented with calls to the g:action-group-query-action function.
Signal Details:
The "action-added" signal
lambda (group name)    :detailed      
group
The g:action-group instance that changed.
name
The string with the name of the action.
Signals that a new action was just added to the group. The signal is emitted after the action has been added and is now visible.
The "action-enabled-changed" signal
lambda (group name enabled)    :detailed      
group
The g:action-group instance that changed.
name
The string with the name of the action.
enabled
The boolean whether the action is enabled or not.
Signals that the enabled status of the named action has changed.
The "action-removed" signal
lambda (group name)    :detailed      
group
The g:action-group instance that changed.
name
The string with the name of the action.
Signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler.
The "action-state-changed" signal
lambda (group name parameter)    :detailed      
group
The g:action-group instance that changed.
name
The string with the name of the action.
parameter
The new g:variant parameter for the state.
Signals that the state of the named action has changed.
See also:
2024-12-27
Function gio:action-group-list-actions (group)
Arguments:
group -- a g:action-group instance
Returns:
The list of strings with the names of the actions in the group.
Details:
Lists the actions contained within the action group.
See also:
2024-12-27
Function gio:action-group-has-action (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to check for
Returns:
The boolean whether the named action exists.
Details:
Checks if the named action exists within the action group.
See also:
2025-2-3
Function gio:action-group-action-enabled (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to query
Returns:
The boolean whether or not the action is currently enabled.
Details:
Checks if the named action within the action group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers.
See also:
2025-2-3
Function gio:action-group-action-parameter-type (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to query
Returns:
The g:variant-type parameter type.
Details:
Queries the type of the parameter that must be given when activating the named action within the action group. When activating the action using the g:action-group-activate-action function, the g:variant-type parameter type given to that function must be of the type returned by this function.

In the case that this function returns nil, you must not give any g:variant parameter, but nil 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.
See also:
2025-2-3
Function gio:action-group-action-state-type (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to query
Returns:
The g:variant-type state type, if the action is stateful.
Details:
Queries the type of the state of the named action within the action group. If the action is stateful then this function returns the g:variant-type state type of the state. All calls to the g:action-group-change-action-state function must give a g:variant parameter of this type and the g:action-group-action-state function will return a g:variant parameter of the same type.

If the action is not stateful then this function will return nil. In that case, the g:action-group-action-state function will return nil and you must not call the g:action-group-change-action-state function.

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.
See also:
2025-2-3
Function gio:action-group-action-state-hint (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to query
Returns:
The g:variant parameter with the state range hint, or cffi:null-pointer.
Details:
Requests a hint about the valid range of values for the state of the named action within the action group.

If a cffi:null-pointer 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 g:variant parameter array is returned then each item in the array is a possible value for the state. If a g:variant parameter pair, that is 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.
See also:
2025-2-3
Function gio:action-group-action-state (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to query
Returns:
The current g:variant parameter with the state of the action, or a cffi:null-pointer.
Details:
Queries the current state of the named action within the action group. If the action is not stateful then a cffi:null-pointer will be returned. If the action is stateful then the type of the return value is the type given by the g:action-group-action-state-type function.
See also:
2025-2-3
Function gio:action-group-change-action-state (group name parameter)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to request the change on
parameter -- a new g:variant parameter for the state
Details:
Request for the state of the named action within the action group to be changed to the parameter argument. The action must be stateful and parameter must be of the correct type, see the g:action-group-action-state-type function. 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 the g:action-group-action-state-hint function.
See also:
2025-2-3
Function gio:action-group-activate-action (group name parameter)
Arguments:
group -- a g:action-group instance
name -- a string for the name of the action to activate
parameter -- a g:variant parameter to the activation
Details:
Activate the named action within the action group. If the action is expecting a parameter, then the correct type of the parameter must be given as parameter. If the action is expecting no parameters then the parameter argument must be a cffi:null-pointer, see the g:action-group-action-parameter-type function.
See also:
2025-2-3
Function gio:action-group-action-added (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of an action in the group
Details:
Emits the "action-added" signal on the action group. This function should only be called by g:action-group implementations.
See also:
#2025-2-3
Function gio:action-group-action-removed (group name)
Arguments:
group -- a g:action-group instance
name -- a string for the name of an action in the action group
Details:
Emits the "action-removed" signal on the action group. This function should only be called by g:action-group implementations.
See also:
#2025-2-3
Function gio:action-group-action-enabled-changed (group name enabled)
Arguments:
group -- a g:action-group instance
name -- a string for the name of an action in the action group
enabled -- a boolean whether or not the action is now enabled
Details:
Emits the "action-enabled-changed" signal on the action group. This function should only be called by g:action-group implementations.
See also:
#2025-2-3
Function gio:action-group-action-state-changed (group name state)
Arguments:
group -- a g:action-group instance
name -- a string for the name of an action in the group
state -- a new g:variant parameter for the state of the named action
Details:
Emits the "action-state-changed" signal on the action group. This function should only be called by g:action-group implementations.
See also:
#2025-2-3

GActionMap

Interface gio:action-map
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The g:action-map interface is implemented by g:action-group implementations that operate by containing a number of named g:action instances, such as a g:simple-action-group object.

One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names, for example by prepending "app." or "win.". This is the motivation for the 'map' part of the interface name.
See also:
2025-2-3
Function gio:action-map-lookup-action (map name)
Arguments:
map -- a g:action-map object
name -- a string for the name of an action
Returns:
The g:action object, or nil.
Details:
Looks up the action with the given name in the action map. If no such action exists, returns nil.
See also:
2025-2-3
Function gio:action-map-add-action-entries (map entries)
Arguments:
map -- a g:action-map object
entries -- a list of descriptions for the actions
Details:
A convenience function for creating multiple g:simple-action instances and adding them to a g:action-map object. Each action in the entries list is constructed from the following parameters:
name
The string with the name of the action.
activate
The callback function to connect to the "activate" signal of the action. This can be nil for stateful actions, in which case the default handler is used. For boolean-stated actions with no parameter, this is a toggle. For other state types, and parameter type equal to the state type, this will be a function that just calls the change-state callback function, which you should provide.
parameter-type
The type of the parameter that must be passed to the activate function for this action, given as a single g:variant-type parameter type string, or nil for no parameter.
state
The initial state for this action, given in g:variant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. Stateless actions should give nil here.
change-state
The callback function to connect to the "change-state" signal of the action. All stateful actions should provide a handler here, stateless actions should not.
All values after name are optional.
Examples:
Using the g:action-map-add-action-entries function:
(defun activate-quit (action parameter)
  (declare (ignore action parameter)))

(defun activate-print (action parameter) (declare (ignore action parameter)))

(defun create-action-group () (let ((entries (list (list "quit" #'activate-quit) (list "print" #'activate-print "s"))) (group (g:simple-action-group-new))) (g:action-map-add-action-entries group entries) group))
See also:
2024-5-14
Function gio:action-map-add-action (map action)
Arguments:
map -- a g:action-map object
action -- a g:action object
Details:
Adds an action to the action map. If the action map already contains an action with the same name as action then the old action is dropped from the action map.
See also:
2024-5-14
Function gio:action-map-remove-action (map name)
Arguments:
map -- a g:action-map object
name -- a string for the name of the action
Details:
Removes the named action from the action map. If no action of this name is in the action map then nothing happens.
See also:
2025-2-3

GSimpleActionGroup

Class gio:simple-action-group
Superclasses:
gio:action-group, gio:action-map, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The g:simple-action-group class is a hash table filled with g:action instances, implementing the g:action-group and g:action-map interfaces.
See also:
#2024-12-27
Function gio:simple-action-group-new ()
Returns:
The new g:simple-action-group instance.
Details:
Creates a new, empty, action group.
See also:
2024-12-27
Function gio:simple-action-group-lookup (group name)
Arguments:
group -- a g:simple-action-group instance
name -- a string with the name of an action
Returns:
The g:action instance, or nil.
Details:
Looks up the action with the name name in the action group. If no such action exists, returns nil.
Warning:
The g:simple-action-group-lookup function has been deprecated since version 2.38 and should not be used in newly written code. Use the g:action-map-lookup-action function.
See also:
#2024-12-27
Function gio:simple-action-group-insert (group action)
Arguments:
group -- a g:simple-action-group instance
action -- a g:action instance
Details:
Adds an action to the action group. If the action group already contains an action with the same name as action then the old action is dropped from the action group. The action group takes its own reference on action.
Warning:
The g:simple-action-group-insert function has been deprecated since version 2.38 and should not be used in newly written code. Use the g:action-map-add-action function.
See also:
#2024-12-27
Function gio:simple-action-group-remove (group name)
Arguments:
group -- a g:simple-action-group instance
name -- a string with the name of the action
Details:
Removes the named action from the action group. If no action of this name is in the action group then nothing happens.
Warning:
The g:simple-action-group-remove function has been deprecated since version 2.38 and should not be used in newly written code. Use the g:action-map-remove-action function.
See also:
#2024-12-27
Function gio:simple-action-group-add-entries (group entries)
Arguments:
group -- a g:simple-action-group instance
entries -- a list of descriptions for the actions
Details:
A convenience function for creating multiple g:simple-action instances and adding them to the action group.
Note:
In the Lisp implementation this function calls the g:action-map-add-action-entries function. See the documentation of the g:action-map-add-action-entries function for more information about the parameters in the list to describe an action.
Warning:
The g:simple-action-group-add-entries function has been deprecated since version 2.38 and should not be used in newly written code. Use the g:action-map-add-action-entries function.
See also:
#2024-12-27

GAction

Interface gio:action
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
enabled
The enabled property of type :boolean (Read / Write)
Whether the action is currently enabled. If the action is disabled then calls to the g:action-activate and g:action-change-state functions have no effect.
Default value: true
name
The name property of type :string (Read)
The name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
Default value: nil
parameter-type
The parameter-type property of type g:variant-type (Read)
The type of the parameter that must be given when activating the action.
state
The state property of type g:variant (Read)
The state of the action, or the cffi:null-pointer value if the action is stateless.
state-type
The state-type property of type g:variant-type (Read)
The parameter type of the state that the action has, or nil if the action is stateless.
Slot Access Functions:
Details:
The g:action interface represents a single named action. The main interface to an action is that it can be activated with the g:action-activate function. This results in the "activate" signal being emitted. An activation has a g:variant parameter, which may be nil. 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 the g:action-change-state function. This call takes a g:variant parameter. 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.

The g:action interface is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including the g:simple-action class.

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 responsible for filtering calls to the g:action-activate and g:action-change-state functions for type safety and for the state being enabled.

Probably the only useful thing to do with a g:action object is to put it inside of a g:simple-action-group object.
See also:
2025-2-3
Accessor gio:action-enabled (object)
Syntax:
(g:action-enabled object) => enabled
(setf (g:action-enabled object) enabled)
Arguments:
object -- a g:action object
enabled -- a boolean whether the action is enabled
Details:
Accessor of the enabled slot of the g:action class. The g:action-enabled function checks if the action is currently enabled. The (setf g:action-enabled) function 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.
See also:
2025-2-3
Accessor gio:action-name (object)
Syntax:
(g:action-name object) => name
Arguments:
action -- a g:action object
name -- a string for the name of the action
Details:
Accessor of the name slot of the g:action class. The g:action-name function queries the name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
See also:
2025-2-3
Accessor gio:action-parameter-type (object)
Syntax:
(g:action-parameter-type object) => vtype
Arguments:
object -- a g:action object
vtype -- a g:variant-type parameter type
Details:
Accessor of the parameter-type slot of the g:action class. Queries the type of the parameter that must be given when activating the action. When activating the action using the g:action-activate function, the g:variant parameter given to that function must be of the type returned by this function.

In the case that this function returns a nil value, you must not give any g:variant parameter, but a cffi:null-pointer value instead.
See also:
2025-2-3
Accessor gio:action-state (object)
Syntax:
(g:action-state object) => state
(setf (g:action-state object) state)
Arguments:
object -- a g:action object
state -- a g:variant parameter for the state of the action
Details:
Accessor of the state slot of the g:action class. Queries the current state of the action. If the action is not stateful then a cffi:null-pointer value will be returned. If the action is stateful then the type of the return value is the type given by the g:action-state-type function.
Examples:
A stateful action with an integer.
(defvar state (g:variant-new-int32 123)) => STATE
(defvar action (g:simple-action-new-stateful "stateful" nil state)) => ACTION
(g:action-state action) => #.(SB-SYS:INT-SAP #X560FD04EFE10)
(g:variant-int32 *) => 123
(setf (g:action-state action) (g:variant-new-int32 999))
=> #.(SB-SYS:INT-SAP #X560FD04F2C40)
(g:action-state action) => #.(SB-SYS:INT-SAP #X560FD04F2C40)
(g:variant-int32 *) => 999    
A simple action with no state returns a cffi:null-pointer value.
(setf action (g:simple-action-new "simple" nil))
=>  #<G-SIMPLE-ACTION {1004B2CE73}>
(g:action-state *) => #.(SB-SYS:INT-SAP #X00000000)    
See also:
2025-2-3
Accessor gio:action-state-type (object)
Syntax:
(g:action-state-type object) => vtype
Arguments:
object -- a g:action object
vtype -- a g:variant-type parameter type, for the state type if the action is stateful
Details:
Accessor of the state-type slot of the action class. Queries the type of the state of the action. If the action is stateful, for example created with the g:simple-action-new-stateful function, then this function returns the g:variant-type parameter type of the state. This is the type of the initial value given as the state. All calls to the g:action-change-state function must give a g:variant parameter of this type and the g:action-state function will return a g:variant parameter of the same type.

If the action is not stateful, for example created with the g:simple-action-new function, then this function will return nil. In that case, the g:action-state function will return a cffi:null-pointer value and you must not call the g:action-change-state function.
See also:
2025-2-3
Function gio:action-name-is-valid (name)
Arguments:
name -- a string for an action name
Returns:
True if the name argument is a valid action name.
Details:
Checks if the action name is valid. The action name is valid if it consists only of alphanumeric characters, plus '-' and '.'. The empty string is not a valid action name. It is an error to call this function with a non UTF-8 action name.
Examples:
(g:action-name-is-valid "action") => T
(g:action-name-is-valid "win.action") => T
(g:action-name-is-valid "win-action") => T
(g:action-name-is-valid "win-action!") NIL
(g:action-name-is-valid "") => NIL    
See also:
2025-2-3
Function gio:action-state-hint (action)
Arguments:
action -- a g:action object
Returns:
The g:variant parameter for the state range hint.
Details:
Requests a hint about the valid range of values for the state of the action. If a cffi:null-pointer value 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 g:variant parameter array is returned then each item in the array is a possible value for the state. If a g:variant parameter pair, for example 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.
See also:
2025-2-3
Function gio:action-change-state (action value)
Arguments:
action -- a g:action object
value -- a g:variant parameter for the new state
Details:
Request for the state of the action to be changed to value. The action must be stateful and the value argument must be of the correct type. See the g:action-state-type function.

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 the g:action-state-hint function.
See also:
2025-2-3
Function gio:action-activate (action &optional parameter)
Arguments:
action -- a g:action object
parameter -- an optional g:variant parameter to the activation
Details:
Activates the action. The optional parameter argument must be the correct type of the parameter for the action, for example the parameter type given at construction time. If the parameter type was a cffi:null-pointer value then the parameter argument must be nil, this is the default value.
See also:
2025-2-3
Function gio:action-parse-detailed-name (detailed)
Arguments:
detailed -- a string for a detailed action name
Returns:
name -- a string with the action name
value -- a g:variant parameter for the target value, or a cffi:null-pointer value for no target
Details:
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 the g:variant-parse function. 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 '.'.
Examples:
;; First format
(g:action-parse-detailed-name "app.action")
=> "app.action"
=> #.(SB-SYS:INT-SAP #X00000000)
;; Second format
(g:action-parse-detailed-name "app.action::target")
=> "app.action"
=> #.(SB-SYS:INT-SAP #X7F5B7000E8D0)
(g:variant-string
    (second (multiple-value-list
        (g:action-parse-detailed-name "app.action::target"))))
=> "target"
;; Third format
(g:action-parse-detailed-name "app.action(42)")
=> "app.action"
=> #.(SB-SYS:INT-SAP #X7F5B7000E870)
(g:variant-int32
    (second (multiple-value-list
        (g:action-parse-detailed-name "app.action(42)"))))
=> 42    
See also:
2025-2-3
Function gio:action-print-detailed-name (name &optional value)
Arguments:
name -- a string for a valid action name
value -- an optional g:variant parameter for the target value
Details:
Formats a detailed action name from an action name and a target value. It is an error to call this function with an invalid action name. This function is the opposite of the g:action-parse-detailed-name function. 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.
Examples:
(g:action-print-detailed-name "action")
=> "action"
(g:action-print-detailed-name "action" (g:variant-new-boolean "t"))
=> "action(true)"
(g:action-print-detailed-name "action" (g:variant-new-int32 42))
=> "action(42)"    
See also:
2025-2-3

GSimpleAction

Class gio:simple-action
Superclasses:
gio:action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
enabled
The enabled property of type :boolean (Read / Write)
Whether the action is currently enabled. If the action is disabled then calls to the g:action-activate and g:action-change-state functions have no effect.
Default value: true
name
The name property of type :string (Read / Write / Construct Only)
The name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
Default value: nil
parameter-type
The parameter-type property of type g:variant-type (Read / Write / Construct Only)
The type of the parameter that must be given when activating the action.
state
The state property of type g:variant (Read / Write / Construct)
The state of the action, or the cffi:null-pointer value if the action is stateless.
state-type
The state-type property of type g:variant-type (Read)
The type of the state that the action has, or nil if the action is stateless.
Returned by:
Slot Access Functions:
Details:
The g:simple-action class is the obvious simple implementation of the g:action interface. This is the easiest way to create an action for purposes of adding it to a g:simple-action-group object.
Signal Details:
The "activate" signal
lambda (action parameter)    :run-last      
action
The g:simple-action object.
parameter
The g:variant parameter to the activation.
Indicates that the action was just activated. The parameter argument will always be of the expected type. In the event that an incorrect type was given, no signal will be emitted.
The "change-state" signal
lambda (action value)    :run-last      
action
The g:simple-action object.
value
The requested g:variant parameter for the state.
Indicates that the action just received a request to change its state. The value argument will always be of the correct state type. In the event that an incorrect type was given, no signal will be emitted. If no handler is connected to this signal then the default behaviour is to call the g:simple-action-state function 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 the g:simple-action-state function from the handler.

Examples: Implementation of a "change-state" signal handler:
(g:signal-connect action "change-state"
                  (lambda (simple value)
                    (let ((requested (g:variant-int32 value)))
                      ;; Volume only goes from 0 to 10
                      (when (and (>= requested 0) (<= requested 10))
                        (setf (g:simple-action-state simple) 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.
See also:
2024-12-29
Accessor gio:simple-action-enabled (object)
Syntax:
(g:simple-action-enabled object) => enabled
(setf (g:simple-action-enabled object) enabled)
Arguments:
object -- a g:simple-action object
enabled -- a boolean whether the action is enabled
Details:
Accessor of the enabled slot of the g:simple-action class. 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.
See also:
2024-12-29
Accessor gio:simple-action-name (object)
Syntax:
(g:simple-action-name object) => name
Arguments:
object -- a g:simple-action object
name -- a string with the name of the action
Details:
Accessor of the name slot of the g:simple-action class. The name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
See also:
2024-12-29
Accessor gio:simple-action-parameter-type (object)
Syntax:
(g:simple-action-parameter-type object) => vtype
Arguments:
object -- a g:simple-action object
vtype -- a g:variant-type parameter type
Details:
Accessor of the parameter-type slot of the g:simple-action class. The type of the parameter that must be given when activating the action.
See also:
2024-12-29
Accessor gio:simple-action-state (object)
Syntax:
(g:simple-action-state object) => value
(setf (g:simple-action-state object) value)
Arguments:
object -- a g:simple-action object
value -- a g:variant parameter for the state
Details:
Accessor of the state slot of the g:simple-action class. Sets the state of the action to value. 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 the g:action-change-state function to request the change.
See also:
2024-12-29
Accessor gio:simple-action-state-type (object)
Syntax:
(g:simple-action-state-type object) => vtype
Arguments:
object -- a g:simple-action object
vtype -- a g:variant-type parameter type
Details:
Accessor of the state-type slot of the g:simple-action class. The type of the state that the action has, or nil if the action is stateless.
See also:
2024-12-29
Function gio:simple-action-new (name vtype)
Arguments:
name -- a string with the name of the action
vtype -- a g:variant-type parameter type or a type string for the parameter to the activate function
Returns:
The new g:simple-action object.
Details:
Creates a new action. The created action is stateless. See the g:simple-action-new-stateful function for a stateful action.
Notes:
A type string for the vtype argument is converted to the g:variant-type parameter type with the g:variant-type-new function.
Examples:
A simple action with no parameter type.
(defvar action (g:simple-action-new "clear" nil)) => ACTION
(g:action-name action) => "clear"
(g:action-enabled action) => T
(g:action-parameter-type action) => NIL
(g:action-state action) => #.(SB-SYS:INT-SAP #X00000000)
(g:action-state-type action) => NIL    
A simple action with a string parameter type.
(setf action (g:simple-action-new "check" "s"))
=> #<G-SIMPLE-ACTION {10022B4AF3}>
(g:action-name action) => "check"
(g:action-enabled action) => T
(g:action-parameter-type action) => #<G-VARIANT-TYPE {10022B5AB3}>
(g:action-state action) => #.(SB-SYS:INT-SAP #X00000000)
(g:action-state-type action) => NIL    
See also:
2024-12-29
Function gio:simple-action-new-stateful (name vtype state)
Arguments:
name -- a string with the name of the action
vtype -- a g:variant-type parameter type or a type string for the parameter to the activate function
state -- a g:variant parameter for the initial state of the action
Returns:
The new g:simple-action object.
Details:
Creates a new stateful action. The state argument is the initial state of the action. All future state values must have the same g:variant-type parameter type as the initial state.
Notes:
A type string for the vtype argument is converted to the g:variant-type parameter type with the g:variant-type-new function.
See also:
2024-12-29
Function gio:simple-action-set-state-hint (action hint)
Arguments:
action -- a g:simple-action object
hint -- a g:variant parameter representing the state hint
Details:
Sets the state hint for the action. See the g:action-state-hint function for more information about action state hints.
See also:
#2024-12-29

GPropertyAction

Class gio:property-action
Superclasses:
gio:action, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
enabled
The enabled property of type :boolean (Read)
Whether the action is currently enabled. If the action is disabled then calls to the g:action-activate and g:action-change-state functions have no effect.
Default value: true
invert-boolean
The invert-boolean property of type :boolean (Read / Write / Construct Only)
If true, the state of the action will be the negation of the property value, provided the property is boolean.
Default value: false
name
The name property of type :string (Read / Write / Construct Only)
The name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
Default value: nil
object
The object property of type g:object (Write / Construct Only)
The object to wrap a property on. The object must be a g:object instance with properties.
Note: In the Lisp binding this property is not readable and not writeable.
parameter-type
The parameter-type property of type g:variant-type (Read)
The type of the parameter that must be given when activating the action.
property-name
The property-name property of type :string (Write / Construct only)
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.
Note: In the Lisp binding this property is not readable und not writeable.
state
The state property of type g:variant (Read)
The state of the action, or the cffi:null-pointer value if the action is stateless.
state-type
The state-type property of type g:variant-type (Read)
The variant parameter type of the state that the action has, or nil if the action is stateless.
Returned by:
Slot Access Functions:
Details:
The g:property-action class is a way to get a g:action object with a state value reflecting and controlling the value of a g: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 g:param-spec instance.

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 enumeration then the state will be string-typed and conversion will automatically be performed between the enumeration value and "nick" string.

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 g:variant parameter 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. The g:property-action object 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 g:action object corresponding to the visible-child-name property of a gtk:stack widget 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 gtk:stack widget.

An anti-example would be to bind to the visible-child-name property of a gtk:stack widget if this value is actually stored in GSettings. In that case, the real source of the value is GSettings. If you want a g:action object to control a setting stored in GSettings, see the g_settings_create_action() function instead, and possibly combine its use with the g_settings_bind() function.
See also:
2024-12-29
Accessor gio:property-action-enabled (object)
Syntax:
(g:property-action-enabled object) => enabled
Arguments:
object -- a g:property-action object
enabled -- a boolean whether the action is enabled
Details:
Accessor of the enabled slot of the g:property-action class. If the action is currently enabled. If the action is disabled then calls to the g:action-activate and g:action-change-state functions have no effect.
See also:
2024-12-29
Accessor gio:property-action-invert-boolean (object)
Syntax:
(g:property-action-invert-boolean object) => invert
Arguments:
object -- a g:property-action object
invert -- a boolean whether the state of the action will be the negation
Details:
If true, the state of the action will be the negation of the property value, provided the property is boolean.
See also:
2024-12-29
Accessor gio:property-action-name (object)
Syntax:
(g:property-action-name object) => name
Arguments:
object -- a g:property-action object
name -- a string with the name of the action
Details:
The name of the action. This is mostly meaningful for identifying the action once it has been added to a g:action-map instance.
See also:
2024-12-29
Accessor gio:property-action-object (object)
Details:
The object slot of the g:property-action class is not readable and not writable.
See also:
2024-12-29
Accessor gio:property-action-parameter-type (object)
Syntax:
(g:property-action-parameter-type object) => type
Arguments:
object -- a g:property-action object
type -- a g:variant-type parameter type
Details:
The type of the parameter that must be given when activating the action.
Examples:
(defvar label (make-instance 'gtk:label))
=> LABEL
(defvar action (g:property-action-new "action" label "xalign"))
=> ACTION
(g:property-action-parameter-type action)
=> #<GLIB:VARIANT-TYPE {10023AE493}>
(g:variant-type-dup-string *)
=> "d"    
See also:
2024-12-29
Accessor gio:property-action-property-name (object)
Details:
The property-name slot of the g:property-action class is not readable and not writable.
See also:
2024-12-29
Accessor gio:property-action-state (object)
Syntax:
(property-action-state object) => state
Arguments:
object -- a g:property-action object
state -- a g:variant parameter for the state of the action
Details:
The state of the action, or the cffi:null-pointer value if the action is stateless.
See also:
2024-12-29
Accessor gio:property-action-state-type (object)
Syntax:
(g:property-action-state-type object) => type
Arguments:
object -- a g:property-action object
type -- a g:variant-type parameter type for the state type of the action
Details:
The variant parameter type of the state that the action has, or nil if the action is stateless.
See also:
2024-12-29
Function gio:property-action-new (name object property)
Arguments:
name -- a string with the name of the action to create
object -- a g:object instance that has the property to wrap
property -- a string with the name of the property
Returns:
The new g:property-action object.
Details:
Creates an action corresponding to the value of property on the object. The property must be existent and readable and writable and not construct-only.
See also:
2024-12-29

GMenuModel

Class gio:menu-model
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
Direct Slots:
None
Details:
The g:menu-model class 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, that is, whether it is stateful, and what kind of state it has, can influence the representation of the item.

The conceptual model of menus in a g:menu-model object is hierarchical: sections and submenus are again represented by g:menu-model objects. Menus themselves do not define their own roles. Rather, the role of a particular g:menu-model object 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.

Figure: Menu

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 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

Figure: Menu model

Notice that the separators visible in the example appear nowhere in the 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, and so on. To support such uses, it is necessary to 'export' information about actions and their representation in menus, which is exactly what the g:action-group exporter and the g:menu-model exporter do for g:action-group and g:menu-model objects. The client-side counterparts to make use of the exported information are GDBusActionGroup and GDBusMenuModel.

The API of the g:menu-model class is very generic, with iterators for the attributes and links of an item, see the g:menu-model-iterate-item-attributes and g:menu-model-iterate-item-links functions. The 'standard' attributes and link types have names: "label", "action", "target", "section", and "submenu".

Items in a g:menu-model object 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 "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. For example, when the model is exported as the application menu of a gtk:application instance, 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.
Signal Details:
The "items-changed" signal
lambda (model position removed added)   :run-last      
model
The g:menu-model object that is changing.
position
The integer with the position of the change.
removed
The integer with the number of items removed.
added
The integer with the number of items added.
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. The 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.
See also:
2024-12-29
Function gio:menu-model-is-mutable (model)
Arguments:
model -- a g:menu-model object
Returns:
True if model is mutable, that is, the "items-changed" signal may be emitted.
Details:
Queries if the menu model is mutable. An immutable menu model will never emit the "items-changed" signal. Consumers of the model may make optimisations accordingly.
See also:
#2024-12-29
Function gio:menu-model-n-items (model)
Arguments:
model -- a g:menu-model object
Returns:
The integer with the number of items in model.
Details:
Query the number of items in the menu model.
See also:
#2024-12-29
Function gio:menu-model-item-attribute-value (model index attribute vtype)
Arguments:
model -- a g:menu-model object
index -- an integer with the index of the item
attribute -- a string with the attribute to query
vtype -- a g:variant-type parameter type with the expected type of the attribute, of nil
Returns:
The g:variant parameter with the value of the attribute.
Details:
Queries the item at position index in model for the attribute specified by attribute. If vtype is not nil then it specifies the expected type of the attribute. If it is nil then any type will be accepted.

If the attribute exists and matches vtype, 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 nil is returned.
See also:
#2024-12-30
Arguments:
model -- a g:menu-model object
index -- an integer with the index of the item
link -- an string with the link to query
Returns:
The linked g:menu-model object, or nil.
Details:
Queries the item at position index in model for the link specified by link. If the link exists, the linked g:menu-model object is returned. If the link does not exist, nil is returned.
See also:
#2024-12-30
Function gio:menu-model-iterate-item-attributes (model index)
Arguments:
model -- a g:menu-model object
index -- an integer with the index of the item
Returns:
The new g:menu-attribute-iter object.
Details:
Creates a g:menu-attribute-iter object to iterate over the attributes of the item at position item in model.
See also:
#2024-12-30
Arguments:
model -- a g:menu-model object
index -- an integer with the index of the item
Returns:
The new g:menu-link-iter object.
Details:
Creates a g:menu-link-iter object to iterate over the links of the item at position index in model.
See also:
#2024-12-30
Function gio:menu-model-items-changed (model pos removed added)
Arguments:
model -- a g:menu-model object
pos -- an integer with the position of the change
removed -- an integer with the number of items removed
added -- an integer with the number of items added
Details:
Requests emission of the "items-changed" signal on model.

This function should never be called except by g:menu-model subclasses. Any other calls to this function will very likely lead to a violation of the interface of the menu 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 main loop entry and not in response to calls, particularly those from the g:menu-model API. Said another way: the menu must not change while user code is running without returning to the main loop.
See also:
#2024-12-30
Class gio:menu-attribute-iter
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The g:menu-attribute-iter class is an opaque structure type.
See also:
2024-12-30
Function gio:menu-attribute-iter-next (iter)
Arguments:
iter -- a g:menu-attribute-iter object
Returns:
True on success, or false if there are no more attributes.
Details:
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.
See also:
#2024-12-30
Function gio:menu-attribute-iter-name (iter)
Arguments:
iter -- a g:menu-attribute-iter object
Returns:
The string with the name of the attribute.
Details:
Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced.
See also:
#2024-12-30
Function gio:menu-attribute-iter-value (iter)
Arguments:
iter -- a g:menu-attribute-iter object
Returns:
The g:variant parameter with the value of the current attribute.
Details:
Gets the value of the attribute at the current iterator position, as a string. The iterator is not advanced.
See also:
#2024-12-30
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The g:menu-link-iter class is an opaque structure type.
See also:
2024-12-30
Arguments:
iter -- a g:menu-link-iter object
Returns:
True on success, or false if there are no more links.
Details:
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.
See also:
#2024-12-30
Arguments:
iter -- a g:menu-link-iter object
Returns:
The string with the name of the link.
Details:
Gets the name of the link at the current iterator position, as a string. The iterator is not advanced.
See also:
#2024-12-30
Arguments:
iter -- a g:menu-link-iter object
Returns:
The g:menu-model object that is linked to.
Details:
Gets the linked g:menu-model object at the current iterator position. The iterator is not advanced.
See also:
#2024-12-30

GMenu

Class gio:menu
Superclasses:
gio:menu-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The g:menu class is an implementation of the abstract g:menu-model class. You populate a g:menu object by adding g:menu-item objects to it.

There are some convenience functions to allow you to directly add items, avoiding a g:menu-item object, for the common cases. To add a regular item, use theg:menu-insert function. To add a section, use the g:menu-insert-section function. To add a submenu, use the g:menu-insert-submenu function.
See also:
2024-12-30
Function gio:menu-new ()
Returns:
The new g:menu object.
Details:
Creates a new g:menu object. The new menu has no items.
See also:
2024-12-30
Function gio:menu-freeze (menu)
Arguments:
menu -- a g:menu object
Details:
Marks the menu as frozen. After the menu is frozen, it is an error to attempt to make any changes to it. In effect this means that the g:menu API must no longer be used.

This function causes the g:menu-model-is-mutable function to begin returning false, which has some positive performance implications.
See also:
2024-12-30
Function gio:menu-insert (menu pos label action)
Arguments:
menu -- a g:menu object
pos -- an integer with the position at which to insert the menu item
label -- a string with the section label, or nil
action -- a detailed action string, or nil
Details:
Convenience function for inserting a normal menu item into the menu. Combine the g:menu-item-new and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-prepend (menu label action)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
action -- a detailed action string, or nil
Details:
Convenience function for prepending a normal menu item to the start of the menu. Combine the g:menu-item-new and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-append (menu label action)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
action -- a detailed action string, or nil
Details:
Convenience function for appending a normal menu item to the end of the menu. Combine the g:menu-item-new and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-insert-item (menu pos item)
Arguments:
menu -- a g:menu object
pos -- an integer with the position at which to insert item
item -- a g:menu-item object to insert
Details:
Inserts a menu item into the menu. The "insertion" is actually done by copying all of the attribute and link values of item and using them to form a new menu item within the menu. As such, item itself is not really inserted, but rather, a menu item that is exactly the same as the one presently described by item.

This means that item is essentially useless after the insertion occurs. Any changes you make to it are ignored unless it is inserted again, at which point its updated values will be copied.

There are many convenience functions to take care of common cases. See the g:menu-insert, g:menu-insert-section and g:menu-insert-submenu functions as well as "prepend" and "append" variants of each of these functions.
See also:
2024-12-30
Function gio:menu-prepend-item (menu item)
Arguments:
menu -- a g:menu object
item -- a g:menu-item object to prepend
Details:
Prepends the menu item to the start of the menu. See the g:menu-insert-item function for more information.
See also:
2024-12-30
Function gio:menu-append-item (menu item)
Arguments:
menu -- a g:menu object
item -- a g:menu-item object to append
Details:
Appends the menu item to the end of the menu. See the g:menu-insert-item function for more information.
See also:
2024-12-30
Function gio:menu-insert-section (menu pos label section)
Arguments:
menu -- a g:menu object
pos -- an integer with the position at which to insert section
label -- a string with the section label, or nil
section -- a g:menu-model object with the items of the section
Details:
Convenience function for inserting a section menu item into menu. Combine the g:menu-item-new-section and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-prepend-section (menu label section)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
section -- a g:menu-model object with the items of the section
Details:
Convenience function for prepending a section menu to the start of the menu. Combine the g:menu-item-new-section and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-append-section (menu label section)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
section -- a g:menu-model object with the items of the section
Details:
Convenience function for appending a section menu to the emd of the menu. Combine the g:menu-item-new-section and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-insert-submenu (menu pos label submenu)
Arguments:
menu -- a g:menu object
pos -- an integer with the position at which to insert submenu
label -- a string with the section label, or nil
submenu -- a g:menu-model object with the items of the submenu
Details:
Convenience function for inserting a submenu into the menu. Combine the g:menu-item-new-submenu and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-prepend-submenu (menu label submenu)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
submenu -- a g:menu-model object with the items of the submenu
Details:
Convenience function for prepending a submenu to the start of the menu. Combine the g:menu-item-new-submenu and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-append-submenu (menu label submenu)
Arguments:
menu -- a g:menu object
label -- a string with the section label, or nil
submenu -- a g:menu-model object with the items of the submenu
Details:
Convenience function for appending a submenu to the end of the menu. Combine the g:menu-item-new-submenu and g:menu-insert-item functions for a more flexible alternative.
See also:
2024-12-30
Function gio:menu-remove (menu pos)
Arguments:
menu -- a g:menu object
pos -- an integer with the position of the menu item to remove
Details:
Removes an item from the menu. The pos argument gives the index of the menu item to remove. It is an error if pos is not in the range from 0 to one less than the number of menu 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, that is, identity of the menu item itself is not preserved.
See also:
2024-12-30
Function gio:menu-remove-all (menu)
Details:
Removes all items in the menu.
See also:
2024-12-30
Class gio:menu-item
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The g:menu-item object is an opaque structure type. You must access it using the API functions.
See also:
2024-12-30
Function gio:menu-item-new (label action)
Arguments:
label -- a string with the section label, or nil
action -- a detailed action string, or nil
Returns:
The new g:menu-item object.
Details:
Creates a new g:menu-item object. If label is not nil it is used to set the "label" attribute of the new menu item.

If action is not nil it is used to set the "action" and possibly the "target" attribute of the new item. See the g:menu-item-set-detailed-action function for more information.
See also:
2024-12-30
Function gio:menu-item-new-section (label section)
Arguments:
label -- a string with the section label, or nil
section -- a g:menu-model object with the menu items of the section
Returns:
The new g:menu-item object.
Details:
Creates a new g:menu-item object representing a section. This is a convenience API around the g:menu-item-new and g:menu-item-set-section functions.

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 the items are added to.

Visual separation is typically displayed between two non-empty sections. If label is not nil then it will be encorporated into this visual indication. This allows for labeled subsections of a menu.
Examples:
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 g:menu objects. The first would be populated with the "Undo" and "Redo" items, and the second with the "Cut", "Copy" and "Paste" items. The first and second menus would then be added as submenus of the third. In XML format, this would look something like the following:
<menu id='edit-menu'>
  <section>
    <item label='Undo'/>
    <item label='Redo'/>
  </section>
  <section>
    <item label='Cut'/>
    <item label='Copy'/>
    <item label='Paste'/>
  </section>
</menu>    
The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items, keeping in mind that the link element defines a new menu that is linked to the containing one. The style of the second example is more verbose and difficult to read, and therefore not recommended except for the purpose of understanding what is really going on.
<menu id='edit-menu'>
  <item>
    <link name='section'>
      <item label='Undo'/>
      <item label='Redo'/>
    </link>
  </item>
  <item>
    <link name='section'>
      <item label='Cut'/>
      <item label='Copy'/>
      <item label='Paste'/>
    </link>
  </item>
</menu>    
See also:
2024-12-30
Function gio:menu-item-new-submenu (label submenu)
Arguments:
label -- a string with the section label, or nil
submenu -- a g:menu-model object with the menu items of the submenu
Returns:
The new g:menu-item object.
Details:
Creates a new g:menu-item object representing a submenu. This is a convenience API around the g:menu-item-new and g:menu-item-set-submenu functions.
See also:
2024-12-30
Function gio:menu-item-new-from-model (model index)
Arguments:
model -- a g:menu-model object
index -- an integer with the index of a menu item in model
Returns:
The new g:menu-item object.
Details:
Creates a g:menu-item object as an exact copy of an existing menu item in a g:menu-model object. The index argument must be valid, that is, be sure to call the g:menu-model-n-items function first.
See also:
2024-12-30
Function gio:menu-item-set-label (item label)
Arguments:
item -- a g:menu-item object
label -- a string with the "label" attribute to set, or nil
Details:
Sets or unsets the "label" attribute of the menu item. If label is not nil it is used as the "label" attribute for the menu item. If it is nil then the "label" attribute is unset.
See also:
2024-12-30
Function gio:menu-item-set-icon (item icon)
Arguments:
item -- a g:menu-item object
icon -- a g:icon object
Details:
Sets or unsets the "icon" attribute on the menu item. This call is the same as calling the g:icon-serialize function and using the result as the value to the g:menu-item-attribute-value function for the "icon" attribute.

This API is only intended for use with "noun" menu items. Things like bookmarks or applications in an "Open With" menu. Do not use it on menu items that correspond to verbs, such as the stock icons for 'Save' or 'Quit'.

If the icon argument is nil then the "icon" attribute is unset.
See also:
2024-12-30
Function gio:menu-item-set-action-and-target-value (item action value)
Arguments:
item -- a g:menu-item object
action -- a string with the name of the "action" attribute for this menu item
value -- a g:variant parameter to use as the action target
Details:
Sets or unsets the "action" and "target" attributes of the menu item. If action is nil then both the "action" and "target" attributes are unset, and value is ignored.

If action is not nil then the "action" attribute is set. The "target" attribute is then set to the value of value if it is not nil or unset otherwise.

Normal menu items, that is 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 the g:action documentation 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, that is with no additional decoration.

If the action has a boolean state then the menu item is usually drawn as a toggle menu item, that is 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, that is 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 the g:menu-item-set-detailed-action function for a equivalent call that is probably more convenient for most uses.
See also:
2024-12-30
Function gio:menu-item-set-detailed-action (item action)
Arguments:
item -- a g:menu-item object
action -- a detailed action string
Details:
Sets the "action" attribute and possibly the "target" attribute of the menu item. The format of action is the same format parsed by the g:action-parse-detailed-name function.

See the g:menu-item-set-action-and-target-value function for a more flexible, but slightly less convenient, alternative. See also the g:menu-item-set-action-and-target-value function for a description of the semantics of the "action" and "target" attributes.
See also:
2024-12-30
Function gio:menu-item-set-section (item section)
Arguments:
item -- a g:menu-item object
section -- a g:menu-model, or nil
Details:
Sets or unsets the "section" link of the menu item to section. The effect of having one menu appear as a section of another is exactly as it sounds: the items from section become a direct part of the menu that item is added to. See the g:menu-item-new-section function for more information about what it means for a menu item to be a section.
See also:
2024-12-30
Function gio:menu-item-set-submenu (item submenu)
Arguments:
item -- a g:menu-item object
submenu -- a g:menu-model object, or nil
Details:
Sets or unsets the "submenu" link of the menu item to submenu. If submenu is not nil, it is linked to. If it is nil then the link is unset.

The effect of having one menu appear as a submenu of another is exactly as it sounds.
See also:
2024-12-30
Function gio:menu-item-attribute-value (item attribute &optional vtype)
Syntax:
(g:menu-item-attribute-value item attribute) => value
(g:menu-item-attribute-value item attribute vtype) => value
(setf (g:menu-item-attribute-value item attribute) value)
Arguments:
item -- a g:menu-item object
attribute -- a string with the attribute name
vtype -- an optional expected g:variant-type parameter type or a type string for the the attribute
value -- a g:variant parameter to use as the value, or nil
Details:
The g:menu-item-attribute-value function queries the named attribute on the menu item. The (setf g:menu-item-attribute-value) function sets or unsets an attribute.

If the vtype argument is specified and the attribute does not have this type, nil is returned. nil is also returned if the attribute simply does not exist.

The attribute to set or unset is specified by attribute. This can be one of the standard attribute names "label", "action", "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 value is not nil then it is used as the new value for the attribute. If value is nil then the attribute is unset. If the g:variant parameter is floating, it is consumed.
See also:
2024-12-30
Syntax:
(g:menu-item-link item link) => model
(setf (g:menu-item-link item link) model)
Arguments:
item -- a g:menu-item object
link -- a string with the type of link to establish or unset
model -- a g:menu-model object to link to, or nil to unset
Details:
The g:menu-item-link function queries the named link on item. The (setf g:menu-item-link) function creates a link from item to model if not nil, or unsets it.

Links are used to establish a relationship between a particular menu item and another menu. For example, the "submenu" attribute is used to associate a submenu with a particular menu item, and the "section" attribute 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.
See also:
2024-12-31

GNotification

GEnum gio:notification-priority
Declaration:
(gobject:define-genum "GNotificationPriority" notification-priority
  (:export t
   :type-initializer "g_notification_priority_get_type")
  (:normal 0)
  (:low 1)
  (:high 2)
  (:urgent 3))  
Values:
:normal
The default priority, to be used for the majority of notifications, for example email messages, software updates, completed download operations.
:low
For notifications that do not require immediate attention. Typically used for contextual background information, such as contact birthdays or local weather.
:high
For events that require more attention, usually because responses are time-sensitive, for example chat and SMS messages or alarms.
:urgent
For urgent notifications, or notifications that require a response in a short space of time, for example phone calls or emergency warnings.
Details:
Priority levels for g:notification instances.
See also:
2024-12-28
Class gio:notification
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The g:notification class 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 the g:notification implementation and other similar APIs is that, if supported by the desktop environment, notifications sent with the g:notification class 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 the g:notification class should be able to be started as a D-Bus service, using the g:application class.

User interaction with a notification, either the default action, or buttons, must be associated with actions on the application, that is, "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 the g:application-send-notification function.
See also:
2024-12-28
Function gio:notification-new (title)
Arguments:
title -- a string with the title of the notification
Returns:
The new g:notification instance.
Details:
Creates a new notification with title as its title. After populating the notification with more details, it can be sent to the desktop shell with the g:application-send-notification function. Changing any properties after this call will not have any effect until resending the notification.
See also:
2024-12-28
Function gio:notification-set-title (notification title)
Arguments:
notification -- a g:notification instance
title -- a string with the new title for the notification
Details:
Sets the title of the notification.
See also:
2024-12-28
Function gio:notification-set-body (notification body)
Arguments:
notification -- a g:notification instance
body -- a string with the body for the notification, or nil
Details:
Sets the body of the notification.
See also:
2024-12-28
Function gio:notification-set-icon (notification icon)
Arguments:
notification -- a g:notification instance
icon -- a g:icon instance with the icon to be shown in the notification
Details:
Sets the icon of the notification.
See also:
2024-12-28
Function gio:notification-set-priority (notification priority)
Arguments:
notification -- a g:notification instance
priority -- a g:notification-priority value
Details:
Sets the priority of the notification. See the g:notification-priority enumeration for possible values.
See also:
2024-12-28
Function gio:notification-set-default-action (notification action)
Arguments:
notifiaction -- a g:notification instance
action -- a string with a detailed action name
Details:
Sets the default action of the notification to action. The action is activated when the notification is clicked on.

The action in action must be an application wide action, it must start with "app.". If the action argument contains a target, the given action will be activated with that target as its parameter. See the g:action-parse-detailed-name function for a description of the format for action.

When no default action is set, the application that the notification was sent on is activated.
See also:
2024-12-28
Function gio:notification-add-button (notification label action)
Arguments:
notification -- a g:notification instance
label -- a string with the label of the button
action -- a string with the detailed action name
Details:
Adds a button to the notification that activates the action in action when clicked. That action must be an application wide action, starting with "app.". If action contains a target, the action will be activated with that target as its parameter. See the g:action-parse-detailed-name function for a description of the format for action.
See also:
2024-12-28

Other Functions in gio

Function gio:settings-list-schemas ()

No documentation string. Possibly unimplemented or incomplete.


Package pango

Pango is a text layout and shaping library. Pango facilitates the layout and shaping of multi-language text. Full-function rendering of text and cross-platform support is had when Pango is used with platform APIs or 3rd party libraries, such as Uniscribe and FreeType, as text rendering backends. Pango-processed text will appear similar under different operating systems. This is the API documentation of a Lisp binding to Pango.

Basic Pango Interfaces

Rendering

The Pango rendering pipeline takes a string of Unicode characters and converts it into glyphs. The functions described in this section accomplish various steps of this process.

Symbols and Functions for Rendering

GFlags pango:shape-flags
Declaration:
(gobject:define-gflags "PangoShapeFlags" shape-flags
  (:export t
   :type-initializer "pango_shape_flags_get_type")
  (:none 0)
  (:round-positions #.(ash 1 0)))  
Values:
:none
Default value.
:round-positions
Round glyph positions and widths to whole device units. This option should be set if the target renderer cannot do subpixel positioning of glyphs.
Details:
Flags influencing the shaping process. These can be passed to the pango:shape-with-flags function.
See also:
2025-3-2
CStruct pango:analysis
Declaration:
(cffi:defcstruct analysis
  (shape-engine :pointer)
  (lang-engine :pointer)
  (font (g:object font))
  (level :uint8)
  (gravity :uint8)
  (flags :uint8)
  (script :uint8)
  (language (g:boxed language))
  (extra-attrs :pointer))  
Values:
shape-engine
Unused.
lang-engine
Unused.
font
The pango:font object with the font for this segment.
level
The bidirectional level for this segment.
gravity
The pango:gravity value with the glyph orientation for this segment.
flags
Boolean flags for this segment.
script
The pango:script value with the detected script for this segment.
language
The pango:language object with the detected language for this segment.
extra-attrs
Extra attributes for this segment.
Slot Access Functions:
Details:
The pango:analysis structure stores information about the properties of a segment of text.
See also:
2025-3-2
Accessor pango:analysis-font (instance)
Syntax:
(pango:analysis-font instance) => font
Arguments:
instance -- a pango:analysis instance
font -- a pango:font instance
Details:
Accessor of the font slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-level (instance)
Syntax:
(pango:analysis-level instance) => level
Arguments:
instance -- a pango:analysis instance
font -- an unsigned integer for the bidirectional level for this segment
Details:
Accessor of the level slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-gravity (instance)
Syntax:
(pango:analysis-gravity instance) => gravity
Arguments:
instance -- a pango:analysis instance
gravity -- a pango:gravity value for the glyph orientation
Details:
Accessor of the gravity slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-flags (instance)
Syntax:
(pango:analysis-flags instance) => flags
Arguments:
instance -- a pango:analysis instance
flags -- an unsigned integer for the boolean flags for this segment
Details:
Accessor of the flags slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-script (instance)
Syntax:
(pango:analysis-script instance) => script
Arguments:
instance -- a pango:analysis instance
script -- a pango:script value for the detected script
Details:
Accessor of the script slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-language (instance)
Syntax:
(pango:analysis-language instance) => language
Arguments:
instance -- a pango:analysis instance
language -- a pango:language instance for the detected language
Details:
Accessor of the language slot of the pango:analysis structure.
See also:
2025-3-2
Accessor pango:analysis-extra-attrs (instance)
Syntax:
(pango:analysis-extra-attrs instance) => attrs
Arguments:
instance -- a pango:analysis instance
attrs -- a list of pango:attribute instances for extra attributes
Details:
Accessor of the extra-attrs slot of the pango:analysis structure.
See also:
2025-3-2
GBoxed pango:item
Declaration:
;; Internal structure to access the fields
(cffi:defcstruct %item
  (offset :int)
  (length :int)
  (num-chars :int)
  (analysis analysis))

(glib:define-gboxed-opaque item "PangoItem" :export t :type-initializer "pango_item_get_type" :alloc (%item-new))
Values:
offset
Byte offset of the start of this item in text.
length
Length of this item in bytes.
num-chars
Number of Unicode characters in the item.
analysis
The pango:analysis instance with the analysis results for the item.
Returned by:
Slot Access Functions:
Details:
The pango:item structure stores information about a segment of text.
See also:
2025-3-2
Accessor pango:item-analysis (instance)
Syntax:
(pango:item-analysis instance) => analysis
Arguments:
instance -- a pango:item instance
analysis -- a pango:analysis instance
Details:
Accessor of the analysis slot of the pango:item structure.
See also:
2025-3-2
Accessor pango:item-length (instance)
Syntax:
(pango:item-length instance) => length
Arguments:
instance -- a pango:item instance
length -- an integer for the length of the item in bytes
Details:
Accessor of the length slot of the pango:item structure.
See also:
2025-3-2
Accessor pango:item-num-chars (instance)
Syntax:
(pango:item-num-chars instance) => num
Arguments:
instance -- a pango:item instance
num -- an integer for the number of Unicode characters in the item
Details:
Accessor of the num-chars slot of the pango:item structure.
See also:
2025-3-2
Accessor pango:item-offset (instance)
Syntax:
(pango:item-offset instance) => offset
Arguments:
instance -- a pango:item instance
offset -- an integer for the byte offset of the start of this item in the text
Details:
Accessor of the offset slot of the pango:item structure.
See also:
2025-3-2
Function pango:item-new ()
Returns:
The newly allocated pango:item instance.
Details:
Creates a new pango:item instance initialized to default values.
See also:
2025-3-2
Function pango:item-copy (item)
Arguments:
item -- a pango:item instance
Returns:
The newly allocated pango:item instance.
Details:
Copy an existing pango:item instance.
See also:
2025-3-2
Function pango:item-split (item index offset)
Arguments:
item -- a pango:item instance
index -- an integer for the byte index of the position to split item, relative to the start of the item
offset -- an integer for the number of chars between the start of item and index
Returns:
The new pango:item instance representing text before index.
Details:
Modifies item to cover only the text after index, and returns a new item that covers the text before index that used to be in item. You can think of index as the length of the returned item.

The index argument may not be 0, and it may not be greater than or equal to the length of item, that is, there must be at least one byte assigned to each item, you cannot create a zero-length item.

The offset argument is the length of the first item in chars, and must be provided because the text used to generate the item is not available, so the pango:item-split function cannot count the char length of the split items itself.
See also:
2025-3-2
Function pango:item-apply-attrs (item iter)
Arguments:
item -- a pango:item instance
iter -- a pango:attr-iterator instance
Details:
Add attributes to a pango:item instance. The idea is that you have attributes that do not affect itemization, such as font features, so you filter them out using the pango:attr-list-filter function, itemize your text, then reapply the attributes to the resulting items using this function.

The iter iterator should be positioned before the range of the item, and will be advanced past it. This function is meant to be called in a loop over the items resulting from itemization, while passing the iter to each call.

Since 1.44
See also:
2025-3-2
Function pango:itemize (context text start length attrs iter)
Arguments:
context -- a pango:context object holding information that affects the itemization process
text -- a string for the text to itemize, must be valid UTF-8
start -- an integer for the first byte in text to process
length -- an integer for the number of bytes, (not characters, to process after start, this must be >= 0
attrs -- a pango:attr-list instance for the set of attributes that apply to text
iter -- a cached pango:attr-iterator attribute iterator, or nil
Returns:
The list of pango:item instances.
Details:
Breaks a piece of text into segments with consistent directional level and shaping engine. Each byte of text will be contained in exactly one of the items in the returned list. The generated list of items will be in logical order, the start offsets of the items are ascending.

The iter argument should be an iterator over attrs currently positioned at a range before or containing start. The iter argument will be advanced to the range covering the position just after start + length, that is, if itemizing in a loop, just keep passing in the same iter.
See also:
2025-3-2
Function pango:itemize-with-base-dir (context direction text start length attrs iter)
Arguments:
context -- a pango:context object holding information that affects the itemization process
direction -- a pango:direction value for the base direction to use for bidirectional processing
text -- a string for the text to itemize, must be valid UTF-8
start -- an integer for the first byte in text to process
length -- an integer for the number of bytes, not characters, to process after start, this must be >= 0
attrs -- a pango:attr-list instance for the set of attributes that apply to text
iter -- a cached pango:attr-iterator attribute iterator, or nil
Returns:
The list of pango:item instances.
Details:
Like the pango:itemize function, but the base direction to use when computing bidirectional levels, is specified explicitly rather than gotten from the pango:context object. See also the pango:context-base-dir function.
See also:
2025-3-2
Function pango:shape (text len analysis)
Arguments:
text -- a string for the text to process
len -- an integer for the length (in bytes) of text
analysis -- a pango:analysis instance from the pango:itemize function
Returns:
The pango:glyph-string instance with the results
Details:
Given a segment of text and the corresponding pango:analysis instance returned from the pango:itemize function, convert the characters into glyphs. You may also pass in only a substring of the item from the pango:itemize function.

It is recommended that you use the pango:shape-full function instead, since that API allows for shaping interaction happening across text item boundaries.

Note that the extra attributes in the analyis that is returned from the pango:itemize function have indices that are relative to the entire paragraph, so you need to subtract the item offset from their indices before calling the pango:shape function.
Notes:
Common Lisp has no function for calculating the byte length of a string. Use, for example, the babel:string-size-in-octets function from the Babel library to perform this calculation.
(setq str "Zwölf Ägypter auf der Straße")
=> "Zwölf Ägypter auf der Straße"
(length str) => 28
(babel:string-size-in-octets str)
=> 31
=> 28    
See also:
2025-3-2
Function pango:shape-full (text paragraph analysis)
Arguments:
text -- a string for the valid UTF-8 text to shape
paragraph -- a string for the text of the paragraph, may be nil
analysis -- a pango:analysis instance from the pango:itemize function
Returns:
The pango:glyph-string instance with the result.
Details:
Given a segment of text and the corresponding pango:analysis instance returned from the pango:itemize function, convert the characters into glyphs. You may also pass in only a substring of the item from the pango:itemize function.

This is similar to the pango:shape function, except it also can optionally take the full paragraph text as input, which will then be used to perform certain cross-item shaping interactions. If you have access to the broader text of which text is part of, provide the broader text as paragraph. If paragraph is nil, item text is used instead.

Note that the extra attributes in the analyis that is returned from the pango:itemize function have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as paragraph, you need to subtract the item offset from their indices before calling the pango:shape-full function.
See also:
2025-3-2
Function pango:shape-with-flags (text paragraph analysis flags)
Arguments:
text -- a string for the valid UTF-8 text to shape
paragraph -- a string for the text of the paragraph, may be nil
analysis -- a pango:analysis instance from the pango:itemize function
flags -- a pango:shape-flags value influencing the shaping process
Returns:
The pango:glyph-string instance with the result.
Details:
Given a segment of text and the corresponding pango:analysis instance returned from the pango:itemize function, convert the characters into glyphs. You may also pass in only a substring of the item from the pango:itemize function.

This is similar to the pango:shape-full function, except it also takes flags that can influence the shaping process.

Note that the extra attributes in the analyis that is returned from the pango:itemize function have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as paragraph, you need to subtract the item offset from their indices before calling the pango:shape-with-flags function.

Since 1.44
See also:
2025-3-2

PangoFontDescription

GEnum pango:style
Declaration:
(gobject:define-genum "PangoStyle" style
  (:export t
   :type-initializer "pango_style_get_type")
  (:normal 0)
  (:oblique 1)
  (:italic 2))  
Values:
:normal
The font is upright.
:oblique
The font is slanted, but in a roman style.
:italic
The font is slanted in an italic style.
Details:
An enumeration specifying the various slant styles possible for a font.
See also:
2023-8-27
GEnum pango:weight
Declaration:
(gobject:define-genum "PangoWeight" weight
  (:export t
   :allow-undeclared-values t
   :type-initializer "pango_weight_get_type")
  (:thin 100)
  (:ultralight 200)
  (:light 300)
  (:semilight 350)
  (:book 380)
  (:normal 400)
  (:medium 500)
  (:semibold 600)
  (:bold 700)
  (:ultrabold 800)
  (:heavy 900)
  (:ultraheavy 1000))  
Values:
:thin
The thin weight.
:ultralight
The ultralight weight.
:light
The light weight.
:semilight
The semilight weight.
:book
The book weight.
:normal
The default weight.
:medium
The normal weight.
:semibold
The semibold weight.
:bold
The bold weight.
:ultrabold
The ultrabold weight.
:heavy
The heavy weight.
:ultraheavy
The ultraheavy weight.
Details:
An enumeration specifying the weight (boldness) of a font. This is a numerical value ranging from 100 to 1000, but there are some predefined values.
Note:
The enumeration allows undeclared values. Therefore, it is possible to pass any integer to functions that expect a pango:weight value.
See also:
2024-3-3
GEnum pango:variant
Declaration:
(gobject:define-genum "PangoVariant" variant
  (:export t
   :type-initializer "pango_variant_get_type")
  (:normal 0)
  (:small-caps 1)
  #+pango-1-50
  (:all-small-caps 2)
  #+pango-1-50
  (:petite-caps 3)
  #+pango-1-50
  (:all-petite-caps 4)
  #+pango-1-50
  (:unicase 5)
  #+pango-1-50
  (:title-caps 6))  
Values:
:normal
A normal font.
:small-caps
A font with the lower case characters replaced by smaller variants of the capital characters.
:all-small-caps
A font with all characters replaced by smaller variants of the capital characters. Since 1.50
:petite-caps
A font with the lower case characters replaced by smaller variants of the capital characters. Petite Caps can be even smaller than Small Caps. Since 1.50
:all-petite-caps
A font with all characters replaced by smaller variants of the capital characters. Petite Caps can be even smaller than Small Caps. Since 1.50
:unicase
A font with the upper case characters replaced by smaller variants of the capital letters. Since 1.50
:title-caps
A font with capital letters that are more suitable for all-uppercase title. Since 1.50
Details:
An enumeration specifying capitalization variant of the font.
See also:
2024-3-3
GEnum pango:stretch
Declaration:
(gobject:define-genum "PangoStretch" stretch
  (:export t
   :type-initializer "pango_stretch_get_type")
  (:ultra-condensed 0)
  (:extra-condensed 1)
  (:condensed 2)
  (:semi-condensed 3)
  (:normal 4)
  (:semi-expanded 5)
  (:expanded 6)
  (:extra-expanded 7)
  (:ultra-expanded 8))  
Values:
:ultra-condensed
Ultra condensed width.
:extra-condensed
Extra condensed width.
:condensed
Condensed width.
:semi-condensed
Semi condensed width.
:normal
The normal widt.
:semi-expanded
Semi expanded width.
:expanded
Expanded width.
:extra-expanded
Extra expanded width.
:ultra-expanded
Ultra expanded width.
Details:
An enumeration specifying the width of the font relative to other designs within a family.
See also:
2024-3-3
GFlags pango:font-mask
Declaration:
(gobject:define-gflags "PangoFontMask" font-mask
  (:export t
   :type-initializer "pango_font_mask_get_type")
  (:family #.(ash 1 0))
  (:style #.(ash 1 1))
  (:variant #.(ash 1 2))
  (:weight #.(ash 1 3))
  (:stretch #.(ash 1 4))
  (:size #.(ash 1 5))
  (:gravity #.(ash 1 6))
  (:variations #.(ash 1 7))
  #+pango-1-56
  (:features #.(ash 1 8)))  
Values:
:family
The font family is specified.
:style
The font style is specified.
:variant
The font variant is specified.
:weight
The font weight is specified.
:stretch
The font stretch is specified.
:size
The font size is specified.
:gravity
The font gravity is specified.
:variations
OpenType font variations are specified.
:features
OpenType font features are specified. Since Pango 1.56
Details:
The bits correspond to fields in a pango:font-description instance that have been set.
See also:
2023-8-27
GBoxed pango:font-description
Declaration:
(glib:define-gboxed-opaque font-description "PangoFontDescription"
  :export t
  :type-initializer "pango_font_description_get_type"
  :alloc (%font-description-new))  
Returned by:
Details:
The pango:font-description structure represents the description of an ideal font. It is opaque, and has no user visible fields. These structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.
See also:
2023-8-27
Function pango:font-description-new ()
Returns:
The newly allocated pango:font-description instance.
Details:
Creates a new font description instance with all fields unset.
See also:
2023-8-27
Function pango:font-description-copy (desc)
Arguments:
desc -- a pango:font-description instance, may be nil
Returns:
The newly allocated pango:font-description instance.
Details:
Makes a copy of a font description.
See also:
2023-8-27
Function pango:font-description-hash (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
The unsigned integer with the hash value.
Details:
Computes a hash of a font description.
See also:
2023-8-27
Function pango:font-description-equal (desc1 desc2)
Arguments:
desc1 -- a pango:font-description instance
desc2 -- another pango:font-description instance
Returns:
True if the two font descriptions are identical, false otherwise.
Details:
Compares two font descriptions for equality. Two font descriptions are considered equal if the fonts they describe are provably identical. This means that their masks do not have to match, as long as other fields are all the same. Two font descriptions may result in identical fonts being loaded, but still compare false.
See also:
2023-8-27
Function pango:font-description-family (desc)
Syntax:
(pango:font-description-family desc) => family
(setf (pango:font-description-family desc) family)
Arguments:
desc -- a pango:font-description instance
family -- a string representing the family name
Details:
The pango:font-description-family function gets the family name field of a font description. The (setf pango:font-description-family) function sets the family name field. The family name represents a family of related font styles, and will resolve to a particular pango:font-family object. In some uses of a pango:font-description instance, it is also possible to use a comma separated list of family names for this field.
See also:
2024-3-3
Function pango:font-description-style (desc)
Syntax:
(pango:font-description-style desc) => style
(setf (pango:font-description-style desc) style)
Arguments:
desc -- a pango:font-description instance
style -- a pango:style value with the style for the font description
Details:
The pango:font-description-style function gets the style field of a font description instance. The (setf pango:font-description-style) function sets the style field. The pango:style enumeration describes whether the font is slanted and the manner in which it is slanted. It can be either :normal, :italic, or :oblique. Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.
See also:
2024-3-3
Function pango:font-description-variant (desc)
Syntax:
(pango:font-description-variant desc) => variant
(setf (pango:font-description-variant desc) variant)
Arguments:
desc -- a pango:font-description instance
variant -- a pango:variant value with the variant type for the font description
Details:
The pango:font-description-variant function gets the variant field of a font description. The (setf pango:font-description-variant) function sets the variant field. The pango:variant value can either be :normal or :small-caps.
See also:
2024-3-3
Function pango:font-description-weight (desc)
Syntax:
(pango:font-description-weight desc) => weight
(setf (pango:font-description-weight desc) weight)
Arguments:
desc -- a pango:font-description instance
weight -- a pango:weight value or an integer for the weight of the font description
Details:
The pango:font-description-weight function gets the weight field of a font description. The (setf pango:font-description-weight) function sets the weight field. The weight field specifies how bold or light the font should be. In addition to the values of the pango:weight enumeration, other intermediate numeric values are possible.
Examples:
(setq desc (pango:font-description-new))
=> #<PANGO:FONT-DESCRIPTION {1005A11E63}>
(pango:font-description-weight desc)
=> :NORMAL
(setf (pango:font-description-weight desc) 450)
=> 450
(pango:font-description-weight desc)
=> 450    
See also:
2024-3-3
Function pango:font-description-stretch (desc)
Syntax:
(pango:font-description-stretch desc) => stretch
(setf (pango:font-description-stretch desc) stretch)
Arguments:
desc -- a pango:font-description instance
stretch -- a pango:stretch value for the stretch of the font description
Details:
The pango:font-description-stretch function gets the stretch field of a font description. The (setf pango:font-description-stretch) function sets the stretch field. The stretch field specifies how narrow or wide the font should be.
See also:
2025-2-20
Function pango:font-description-size (desc)
Syntax:
(pango:font-description-size desc) => size
(setf (pango:font-description-size desc) size)
Arguments:
desc -- a pango:font-description instance
size -- an integer for the size of the font in points, scaled by the pango:+scale+ constant
Details:
The pango:font-description-size function gets the size field of a font description in points or device units. The (setf pango:font-description-size) function sets the size field. This is mutually exclusive with the pango:font-description-set-absolute-size function.

A size value of (* 10 pango:+scale+) is a 10 point font. The conversion factor between points and device units depends on the system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 pixel font. Use the pango:font-description-set-absolute-size function if you need a particular size in device units.

You must call the pango:font-description-size-is-absolute function to find out which is the case. Returns 0 if the size field has not previously been set or it has been set to 0 explicitly. Use the pango:font-description-set-fields function to find out if the field was explicitly set or not.
See also:
2024-3-3
Function pango:font-description-set-absolute-size (desc size)
Arguments:
desc -- a pango:font-description instance
size -- a number coerced to a double float for the new size, in Pango units
Details:
Sets the size field of a font description, in device units. There are pango:+scale+ Pango units in one device unit. For an output backend where a device unit is a pixel, a size value of (* 10 pango:+scale+) gives a 10 pixel font.

This is mutually exclusive with the pango:font-description-size function which sets the font size in points.
See also:
2024-3-4
Function pango:font-description-size-is-absolute (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
Whether the size for the font description is in points or device units.
Details:
Determines whether the size of the font is in points (not absolute) or device units (absolute). See the pango:font-description-size and pango:font-description-set-absolute-size functions. Use the pango:font-description-set-fields function to find out if the size field of the font description was explicitly set or not.
See also:
2024-3-3
Function pango:font-description-gravity (desc)
Syntax:
(pango:font-description-gravity desc) => gravity
(setf (pango:font-description-gravity desc) gravity)
Arguments:
desc -- a pango:font-description instance
gravity -- a pango:gravity value for the gravity for the font description
Details:
The pango:font-description-gravity function gets the gravity field of a font description. The (setf pango:font-description-gravity) function sets the gravity field. The gravity field specifies how the glyphs should be rotated. If gravity is :auto, this actually unsets the gravity mask on the font description.

This function is seldom useful to the user. Gravity should normally be set on a pango:context object.
See also:
2024-3-3
Function pango:font-description-variations (desc)
Syntax:
(pango:font-description-variations desc) => variations
(setf (pango:font-description-variations desc) variations)
Arguments:
desc -- a pango:font-description instance
variations -- a string representing the variations
Details:
The pango:font-description-variations function gets the variations field of a font description. The (setf pango:font-description-variations) function sets the variations field. OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight.

The format of the variations string is AXIS1=VALUE, AXIS2=VALUE ..., with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range.

Pango does not currently have a way to find supported axes of a font. Both the HarfBuzz or FreeType libraries have API for this.
See also:
2024-3-3
Function pango:font-description-set-fields (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
The list with the pango:font-mask values set corresponding to the fields in desc that have been set.
Details:
Determines which fields in a font description have been set.
Example:
(pango:font-description-from-string "Sans Bold 16")
=> #<PANGO:FONT-DESCRIPTION {10077E5773}>
(pango:font-description-set-fields *)
=> (:FAMILY :STYLE :VARIANT :WEIGHT :STRETCH :SIZE)    
See also:
2024-3-4
Function pango:font-description-unset-fields (desc unset)
Arguments:
desc -- a pango:font-description instance
unset -- a list with the pango:font-mask values in desc to unset
Details:
Unsets some of the fields in a font description. The unset fields will get back to their default values.
See also:
2024-3-4
Function pango:font-description-merge (desc merge replace)
Arguments:
desc -- a pango:font-description instance
merge -- a pango:font-description instance to merge from, or nil
replace -- if true, replace fields in desc with the corresponding values from merge, even if they are already exist
Details:
Merges the fields that are set in merge into the fields in desc. If replace is false, only fields in desc that are not already set are affected. If true, then fields that are already set will be replaced as well.

If merge is nil, this function performs nothing.
See also:
2024-3-4
Function pango:font-description-better-match (desc old new)
Arguments:
desc -- a pango:font-description instance
old -- a pango:font-description instance, or nil
new -- a pango:font-description instance
Returns:
True if new is a better match.
Details:
Determines if the style attributes of new are a closer match for desc than those of old are, or if old is nil, determines if new is a match at all. Approximate matching is done for weight and style. Other style attributes must match exactly. Style attributes are all attributes other than family and size-related attributes. Approximate matching for style considers :oblique and :italic as matches, but not as good a match as when the styles are equal.

Note that old must match desc.
See also:
#2023-8-27
Function pango:font-description-from-string (str)
Arguments:
str -- a string representation of a font description
Returns:
The new pango:font-description instance.
Details:
Creates a new font description from a string representation. The string representation has the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]", where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (in points) or optionally followed by the unit modifier "px" for absolute size. VARIATIONS is a comma-separated list of font variation specifications of the form "@axis=value" (the = sign is optional).

The following words are understood as styles:
"Normal"   "Roman"   "Oblique"   "Italic"  
The following words are understood as variants:
"Small-Caps"  
The following words are understood as weights:
"Thin"          "Ultra-Light"   "Extra-Light"   "Light"
"Semi-Light"    "Demi-Light"    "Book"          "Regular"
"Medium"        "Semi-Bold"     "Demi-Bold"     "Bold"
"Ultra-Bold"    "Extra-Bold"    "Heavy"         "Black"
"Ultra-Black"   "Extra-Black"  
The following words are understood as stretch values:
"Ultra-Condensed"  "Extra-Condensed"  "Condensed"       "Semi-Condensed"
"Semi-Expanded"    "Expanded"         "Extra-Expanded"  "Ultra-Expanded"  
The following words are understood as gravity values:
"Not-Rotated"   "South"   "Upside-Down"    "North"
"Rotated-Left"  "East"    "Rotated-Right"  "West"  
Any one of the options may be absent. If FAMILY-LIST is absent, then the familiy name of the resulting font description will be initialized to NULL. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.
Examples:
A typical example is:
(pango:font-description-from-string "Cantarell Italic Light 15 @wght=200")
=> #<PANGO:FONT-DESCRIPTION {10077E7DC3}>
(pango:font-description-to-string *)
"Cantarell Light Italic 15 @wght=200"    
See also:
2025-2-20
Function pango:font-description-to-string (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
A new string with a representation of a font description.
Details:
Creates a string representation of a font description. See the pango:font-description-from-string function for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option.
See also:
2024-3-4
Function pango:font-description-to-filename (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
The string with a filname.
Details:
Creates a filename representation of a font description. The filename is identical to the result from calling the pango:font-description-to-string function, but with underscores instead of characters that are untypical in filenames, and in lower case only.
Example:
(pango:font-description-from-string "Sans Bold 16")
=> #<PANGO:FONT-DESCRIPTION {1007EF4DF3}>
(pango:font-description-to-filename *)
=> "sans_bold_16"    
See also:
2024-3-4

PangoFontMetrics

GBoxed pango:font-metrics
Details:
A pango:font-metrics structure holds the overall metric information for a font, possibly restricted to a script. The fields of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning.
See also:
2023-8-27
Function pango:font-metrics-ascent (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the ascent, in Pango units.
Details:
Gets the ascent from a font metrics structure. The ascent is the distance from the baseline to the logical top of a line of text. The logical top may be above or below the top of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.
See also:
2024-3-4
Function pango:font-metrics-descent (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the descent, in Pango units.
Details:
Gets the descent from a font metrics instance. The descent is the distance from the baseline to the logical bottom of a line of text. The logical bottom may be above or below the bottom of the actual drawn ink. It is necessary to lay out the text to figure where the ink will be.
See also:
2024-3-4
Function pango:font-metrics-height (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the height, in Pango units.
Details:
Gets the line height from a font metrics instance. The line height is the distance between successive baselines in wrapped text. If the line height is not available, 0 is returned.

Since 1.44
See also:
2024-3-4
Function pango:font-metrics-approximate-char-width (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the character width, in Pango units.
Details:
Gets the approximate character width for a font metrics instance. This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this.
See also:
2024-3-4
Function pango:font-metrics-approximate-digit-width (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the digit width, in Pango units.
Details:
Gets the approximate digit width for a font metrics instance. This is merely a representative value useful, for example, for determining the initial size for a window. Actual digits in text can be wider or narrower than this, though this value is generally somewhat more accurate than the result of the pango:font-metrics-approximate-char-width function for digits.
See also:
2024-3-4
Function pango:font-metrics-underline-thickness (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the suggested underline thickness, in Pango units.
Details:
Gets the suggested thickness to draw for the underline.
See also:
2024-3-4
Function pango:font-metrics-underline-position (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the suggested underline position, in Pango units.
Details:
Gets the suggested position to draw the underline. The value returned is the distance above the baseline of the top of the underline. Since most fonts have underline positions beneath the baseline, this value is typically negative.
See also:
2024-3-4
Function pango:font-metrics-strikethrough-thickness (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the suggested strikethrough thickness, in Pango units.
Details:
Gets the suggested thickness to draw for the strikethrough.
See also:
2024-3-4
Function pango:font-metrics-strikethrough-position (metrics)
Arguments:
metrics -- a pango:font-metrics instance
Returns:
The integer with the suggested strikethrough position, in Pango units.
Details:
Gets the suggested position to draw the strikethrough. The value returned is the distance above the baseline of the top of the strikethrough.
See also:
2024-3-4

Fonts

Pango supports a flexible architecture where a particular rendering architecture can supply an implementation of fonts. The pango:font class represents an abstract rendering-system-independent font. Pango provides routines to list available fonts, and to load a font of a given description.
Class pango:font
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The pango:font class is used to represent a font in a rendering-system-independent matter.
See also:
2024-3-5
Function pango:font-describe (font)
Arguments:
font -- a pango:font object
Returns:
A newly allocated pango:font-description instance.
Details:
Returns a description of the font, with font size set in points. Use the pango:font-describe-with-absolute-size function if you want the font size in device units.
See also:
2024-3-5
Function pango:font-describe-with-absolute-size (font)
Arguments:
font -- a pango:font object
Returns:
A newly allocated pango:font-description instance.
Details:
Returns a description of the font, with absolute font size set, in device units. Use the pango:font-describe function if you want the font size in points.
See also:
2024-3-5
Function pango:font-face (font)
Arguments:
font -- a pango:font object
Returns:
The pango:font-face object.
Details:
Gets the Pango font face to which the given font belongs.

Since 1.46
See also:
2024-3-5
Function pango:font-coverage (font language)
Arguments:
font -- a pango:font object
language -- a pango:language instance
Returns:
A newly allocated pango:coverage object.
Details:
Computes the coverage map for a given font and language tag.
See also:
2024-3-5
Function pango:font-has-char (font char)
Arguments:
font -- a pango:font object
char -- a character or a char code with a Unicode character
Returns:
Returns whether the font provides a glyph for the given character.
Details:
Returns true if font can render the given character.

Since 1.44
See also:
2024-3-5
Function pango:font-glyph-extents (font glyph ink logical)
Arguments:
font -- a pango:font object
glyph -- an unsigned integer for the glyph index
ink -- a pango:rectangle instance used to store the extents of the glyph as drawn or nil to indicate that the result is not needed
logical -- a pango:rectangle instance used to store the logical extents of the glyph or nil to indicate that the result is not needed
Details:
Gets the logical and ink extents of a glyph within a font. The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing coordinates extending to the right and down. The pango:ascent, pango:descent, pango:lbearing, and pango:rbearing functions can be used to convert from the extents rectangle to more traditional font metrics. The units of the rectangles are in (/ 1 pango:+scale+) of a device unit.

If the font argument is nil, this function gracefully sets some sane values in the output variables and returns.
See also:
2024-3-5
Function pango:font-metrics (font language)
Arguments:
font -- a pango:font object
language -- a pango:language instance with the language tag used to determine which script to get the metrics for, or nil to indicate to get the metrics for the entire font
Returns:
The pango:font-metrics instance.
Details:
Gets overall metric information for a font. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.

If the font argument is nil, this function gracefully sets some sane values in the output variables and returns.
See also:
2024-3-5
Function pango:font-font-map (font)
Arguments:
font -- a pango:font object, or nil
Returns:
The pango:font-map object for the font, or nil if font is nil
Details:
Gets the font map for which the font was created.
See also:
2024-3-5
Function pango:font-languages (font)
Arguments:
font -- a pango:font object
Returns:
The list with the pango:language instances for font.
Details:
Returns the languages that are supported by the font backend. If the font backend does not provide this information, nil is returned. For the fontconfig backend, this corresponds to the FC_LANG member of the FcPattern.

Since 1.50
See also:
2024-3-5
Function pango:font-serialize (font)
Arguments:
font -- a pango:font object
Returns:
The g:bytes instance containing the serialized form of font.
Details:
Serializes the font in a way that can be uniquely identified. There are no guarantees about the format of the output across different versions of Pango. The intended use of this function is testing, benchmarking and debugging. The format is not meant as a permanent storage format.

To recreate a font from its serialized form, use the pango:font-deserialize function.

Since 1.50
See also:
2024-3-5
Function pango:font-deserialize (context bytes)
Arguments:
context -- a pango:context object
bytes -- a g:bytes object containing the data
Returns:
The new pango:font object.
Details:
Loads data previously created via the pango:font-serialize function. For a discussion of the supported format, see that function.

Since 1.50
Note:
To verify that the returned font is identical to the one that was serialized, you can compare bytes to the result of serializing the font again.
See also:
2024-11-21
Class pango:font-family
Superclasses:
gio:list-model, gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
is-monospace
The is-monospace property of type :boolean (Read)
Whether this is a monospace font. Since 1.52
Default value: false
is-variable
The is-variable property of type :boolean (Read)
Whether this is a variable font. Since 1.52
Default value: false
item-type
The item-type property of type g:type-t (Read)
The type of items contained in the list.
n-items
The n-items property of type :uint (Read)
The number of items contained in the list.
Default value: 0
name
The name property of type :string (Read)
The name of the the font family. Since 1.52
Default value: nil
Slot Access Functions:
Details:
The pango:font-family class is used to represent a family of related font faces. The faces in a family share a common design, but differ in slant, weight, width and other aspects.
See also:
2024-5-25
Accessor pango:font-family-is-monospace (object)
Syntax:
(pango:font-family-is-monospace object) => setting
Arguments:
object -- a pango:font-family object
setting -- true if object is monospace
Details:
A monospace font is a font designed for text display where the characters form a regular grid. For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters. The g_unichar_iswide() function returns a result that indicates whether a character is typically double-width in a monospace font.

The best way to find out the grid-cell size is to call the pango:font-metrics-approximate-digit-width function, since the results of the pango:font-metrics-approximate-char-width function may be affected by double-width characters.

Since 1.52
See also:
2024-5-25
Accessor pango:font-family-is-variable (object)
Syntax:
(pango:font-family-is-variable object) => setting
Arguments:
object -- a pango:font-family object
setting -- true if object is variable
Details:
A variable font is a font which has axes that can be modified to produce different faces.

Since 1.52
See also:
2024-5-25
Accessor pango:font-family-item-type (object)
Syntax:
(pango:font-family-item-type object) => type
Arguments:
object -- a pango:font-family object
type -- a g:type-t type ID
Details:
Accessor of the item-type slot of the pango:font-family class. The pango:font-family-item-type function returns the type of items contained in the list.
Warning:
This function does not return a GType but a pointer with an address value that is the GType. This is possibly a bug in the Pango library. You get the correct GType with the g:list-model-item-type function of the g:list-model interface.
See also:
2024-3-5
Accessor pango:font-family-n-items (object)
Syntax:
(pango:font-family-n-items object) => n-items
Arguments:
object -- a pango:font-family object
n-items -- an unsigned integer
Details:
Accessor of the n-items slot of the pango:font-family class. The pango:font-family-n-items function returns the number of items contained in the list.
See also:
2024-3-5
Accessor pango:font-family-name (object)
Syntax:
(pango:font-family-name object) => name
Arguments:
object -- a pango:font-family object
name -- a string with the name of object
Details:
Gets the name of the font family. The name is unique among all fonts for the font backend and can be used in a pango:font-description instance to specify that a face from this family is desired.

Since 1.52
See also:
2024-5-25
Function pango:font-family-list-faces (family)
Arguments:
family -- a pango:font-family object
Returns:
The list of pango:font-face objects, or nil.
Details:
Lists the different font faces that make up family. The faces in a family share a common design, but differ in slant, weight, width and other aspects. You get the number of font faces contained in the font family with the pango:font-family-n-items function.
See also:
2024-3-5
Function pango:font-family-face (family name)
Arguments:
family -- a pango:font-family object
name -- a string with the name of a fpmt face, if name is nil, the default font face of the font family is returned
Returns:
The pango:font-face object, or nil if no face with the given name exists.
Details:
Gets the Pango font face of the given font family with the given name.

Since 1.46
See also:
2024-3-5
Class pango:font-face
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The pango:font-face class is used to represent a group of fonts with the same family, slant, weight, width, but varying sizes.
See also:
2024-3-5
Function pango:font-face-face-name (face)
Arguments:
face -- a pango:font-face object
Returns:
The face name for face.
Details:
Gets a name representing the style of this face among the different faces in the pango:font-family for the face. This name is unique among all faces in the family and is suitable for displaying to users.
See also:
2024-3-5
Function pango:font-face-list-sizes (face)
Arguments:
face -- a pango:font-face object
Returns:
The list of integer with the available sizes for a font.
Details:
List the available sizes for a font. This is only applicable to bitmap fonts. For scalable fonts, returns nil. The sizes returned are in Pango units and are sorted in ascending order.
See also:
2024-3-5
Function pango:font-face-describe (face)
Arguments:
face -- a pango:font-face object
Returns:
The newly created pango:font-description instance holding the description of face.
Details:
Returns the family, style, variant, weight and stretch of a font face. The size field of the resulting font description will be unset.
See also:
2024-3-5
Function pango:font-face-is-synthesized (face)
Arguments:
face -- a pango:font-face object
Returns:
The boolean whether face is synthesized.
Details:
Returns whether a font face is synthesized by the underlying font rendering engine from another face, perhaps by shearing, emboldening, or lightening it.
See also:
2024-3-5
Function pango:font-face-family (face)
Arguments:
face -- a pango:font-face object
Returns:
The pango:font-family object.
Details:
Gets the Pango font family that the font face belongs to.

Since 1.46
See also:
2024-3-5
Class pango:font-map
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
item-type
The item-type property of type g:type-t (Read)
The type of items contained in the list.
n-items
The n-items property of type :uint (Read)
The number of items contained in the list.
Default value: 0
Slot Access Functions:
Details:
The pango:font-map class represents the set of fonts available for a particular rendering system. This is a virtual object with implementations being specific to particular rendering systems.
2024-3-6
Accessor pango:font-map-item-type (object)
Syntax:
(pango:font-map-item-type object) => type
Arguments:
object -- a pango:font-map object
type -- a g:type-t type ID
Details:
Accessor of the item-type slot of the pango:font-map class. The pango:font-map-item-type function returns the type of items contained in the list.
Warning:
This function does not return a GType but a pointer with an address value that is the GType. This is possibly a bug in the Pango library. You get the correct GType with the g:list-model-item-type function of the g:list-model interface.
See also:
2024-3-5
Accessor pango:font-map-n-items (object)
Syntax:
(pango:font-map-n-items object) => n-items
Arguments:
object -- a pango:font-map object
n-items -- an unsigned integer
Details:
Accessor of the n-items slot of the pango:font-map class. The pango:font-map-n-items function returns the number of items contained in the list.
See also:
2024-3-5
Function pango:font-map-create-context (fontmap)
Arguments:
fontmap -- a pango:font-map object
Returns:
The newly allocated pango:context object.
Details:
Creates a Pango context connected to fontmap. This is equivalent to the pango:context-new function followed by the pango:context-font-map function.

If you are using Pango as part of a higher-level system, that system may have it's own way of create a Pango context. For instance, the GTK toolkit has the gtk:widget-pango-context function. Use this instead.
See also:
2024-3-6
Function pango:font-map-load-font (fontmap context desc)
Arguments:
fontmap -- a pango:font-map object
context -- a pango:context object the font will be used with
desc -- a pango:font-description instance describing the font to load
Returns:
The newly allocated pango:font loaded, or nil if no font matched.
Details:
Load the font in the fontmap that is the closest match for desc.
See also:
2024-3-6
Function pango:font-map-load-fontset (fontmap context desc language)
Arguments:
fontmap -- a pango:font-map object
context -- a pango:context object the font will be used with
desc -- a pango:font-description instance describing the font to load
language -- a pango:language instance the fonts will be used for
Returns:
The newly allocated pango:fontset object loaded, or nil if no font matched.
Details:
Load a set of fonts in the fontmap that can be used to render a font matching desc.
See also:
2024-3-6
Function pango:font-map-list-families (fontmap)
Arguments:
fontmap -- a pango:font-map object
Returns:
The list of pango:font-family objects, or nil.
Details:
List all families for a font map.
See also:
2024-3-6
Function pango:font-map-family (fontmap name)
Arguments:
fontmap -- a pango:font-map object
name -- a string with a family name
Returns:
The pango:font-family object.
Details:
Gets a font family by name.

Since 1.46
See also:
2024-3-6
Function pango:font-map-serial (fontmap)
Arguments:
fontmap -- a pango:font-map object
Returns:
The unsigned integer with the current serial number of fontmap.
Details:
Returns the current serial number of fontmap. The serial number is initialized to a small number larger than zero when a new font map is created and is increased whenever the font map is changed. It may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals".

The font map can only be changed using backend-specific API, like changing font map resolution.

This can be used to automatically detect changes to a Pango font map, like in a pango:context object.
See also:
2024-3-6
Function pango:font-map-changed (fontmap)
Arguments:
fontmap -- a pango:font-map object
Details:
Forces a change in the context, which will cause any pango:context object using this font map to change. This function is only useful when implementing a new backend for Pango, something applications will not do. Backends should call this function if they have attached extra data to the context and such data is changed.
See also:
2024-3-6
Class pango:fontset
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The pango:fontset object represents a set of pango:font objects to use when rendering text. It is the result of resolving a pango:font-description instance against a particular pango:context object. It has operations for finding the component font for a particular Unicode character, and for finding a composite set of metrics for the entire fontset.
Example:
Code fragement for getting the fontset:
(let* ((fontmap (pango:cairo-font-map-default))
       (context (pango:font-map-create-context fontmap))
       (desc (pango:font-description-from-string "Sans Italic 12"))
       (lang (pango:language-default))
       (fontset (pango:font-map-load-fontset fontmap context desc lang)))
  fontset)
=> #<PANGO:FONTSET {10026D1863}>    
See also:
2024-3-4
Function pango:fontset-font (fontset char)
Arguments:
fontset -- a pango:fontset object
char -- a character or a char code with a Unicode character
Returns:
The pango:font object.
Details:
Returns the font in the fontset that contains the best glyph for the Unicode character char.
See also:
2024-3-4
Function pango:fontset-metrics (fontset)
Arguments:
fontset -- a pango:fontset object
Returns:
The pango:font-metrics instance.
Details:
Get overall metric information for the fonts in the fontset.
See also:
2024-3-4
Callback pango:fontset-foreach-func
Syntax:
lambda (fontset font) => result
Arguments:
fontset -- a pango:fontset object
font -- a pango:font object from fontset
result -- if true, stop iteration and return immediately
Details:
A callback function used by the pango:fontset-foreach function when enumerating the fonts in a fontset.
See also:
2024-5-25
Function pango:fontset-foreach (fontset func)
Arguments:
fontset -- a pango:fontset object
func -- a pango:fontset-foreach-func callback function
Details:
Iterates through all the fonts in a fontset, calling func for each one. If func returns true, that stops the iteration.
Examples:
Code fragment for counting the fonts in a fontset and for printing a list of the font descriptions.
(let ((count 0))
  (pango:fontset-foreach fontset
          (lambda (fontset font)
            (declare (ignore fontset))
            (let* ((desc (pango:font-describe font))
                   (str (pango:font-description-to-string desc)))
              (format t "~a : ~a~%" count str)
              (incf count)
              nil)))
  count)    
See also:
2024-5-25

Glyph Storage

Structures for storing information about glyphs. The pango:shape function produces a string of glyphs which can be measured or drawn to the screen. The following structures are used to store information about glyphs.
Type pango:glyph
Details:
A pango:glyph type represents a single glyph in the output form of a string. This type is implemented as the :uint32 foreign type.
See also:
2024-3-5
GBoxed pango:glyph-string
Details:
The pango:glyph-string structure is used to store strings of glyphs with geometry and visual attribute information. The storage for the glyph information is owned by the structure which simplifies memory management.
See also:
2024-3-6
Function pango:glyph-string-new ()

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-copy (string)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-set-size (string len)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-extents (glyph font ink logical)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-extents-range (glyph start end font ink logical)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-width (glyphs)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-index-to-x (glyphs text len analysis index trailing)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-x-to-index (glyphs text len analysis xpos trailing)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-string-logical-widths (glyphs text len level widths)

No documentation string. Possibly unimplemented or incomplete.

GBoxed pango:glyph-item
Details:
A pango:glyph-item structure is a pair of a pango:item instance and the glyphs resulting from shaping the text corresponding to an item. As an example of the usage of the pango:glyph-item structure, the results of shaping text with the pango:layout class is a list of pango:layout-line objects, each of which contains a list of pango:glyph-item instances.
See also:
2024-3-6
Function pango:glyph-item-copy (item)

No documentation string. Possibly unimplemented or incomplete.

Function pango:glyph-item-split (item text index)

No documentation string. Possibly unimplemented or incomplete.

Text Attributes

Attributed text is used in a number of places in Pango. It is used as the input to the itemization process and also when creating a Pango layout. The data types and functions in this section are used to represent and manipulate sets of attributes applied to a portion of text.

Types and functions for text attributes

Constant pango:+scale-xx-small+
Initial Value:
(/ 1.0d0 (* 1.2d0 1.2d0 1.2d0))
Details:
The scale factor for three shrinking steps.
2025-1-1
Constant pango:+scale-x-small+
Initial Value:
(/ 1.0d0 (* 1.2d0 1.2d0))
Details:
The scale factor for two shrinking steps.
2025-1-1
Constant pango:+scale-small+
Initial Value:
(/ 1.0d0 1.2d0)
Details:
The scale factor for one shrinking step.
2025-1-1
Constant pango:+scale-medium+
Initial Value:
1.0d0
Details:
The scale factor for normal size.
2025-1-1
Constant pango:+scale-large+
Initial Value:
1.2d0
Details:
The scale factor for one magnification step.
2025-1-1
Constant pango:+scale-x-large+
Initial Value:
(* 1.2d0 1.2d0)
Details:
The scale factor for two magnification steps.
2025-1-1
Constant pango:+scale-xx-large+
Initial Value:
(* 1.2d0 1.2d0 1.2d0)
Details:
The scale factor for three magnification steps.
2025-1-1
GEnum pango:attr-type
Declaration:
(gobject:define-genum "PangoAttrType" attr-type
  (:export t
   :allow-undeclared-values t
   :type-initializer "pango_attr_type_get_type")
  (:invalid 0)
  (:language 1)
  (:family 2)
  (:style 3)
  (:weight 4)
  (:variant 5)
  (:stretch 6)
  (:size 7)
  (:font-desc 8)
  (:foreground 9)
  (:background 10)
  (:underline 11)
  (:strikethrough 12)
  (:rise 13)
  (:shape 14)
  (:scale 15)
  (:fallback 16)
  (:letter-spacing 17)
  (:underline-color 18)
  (:strikethrough-color 19)
  (:absolute-size 20)
  (:gravity 21)
  (:gravity-hint 22)
  (:font-features 23)
  (:foreground-alpha 24)
  (:background-alpha 25)
  (:allow-breaks 26)
  (:show 27)
  (:insert-hyphens 28)
  (:overline 29)
  (:overline-color 30)
  (:line-height 31)
  (:absolute-line-height 32)
  (:text-transform 33)
  (:word 34)
  (:sentence 35)
  (:baseline-shift 36)
  (:font-scale 37))  
Values:
:invalid
Does not happen.
:language
Language.
:family
Font family name list.
:style
Font slant style.
:weight
Font weight.
:variant
Font variant, normal or small caps.
:stretch
Font stretch.
:size
Font size in points scaled by the pango:+scale+ value.
:font-desc
Font description.
:foreground
Foreground color.
:background
Background color.
:underline
Whether the text has an underline.
:strikethrough
Whether the text is struck-through.
:rise
Baseline displacement.
:shape
Shape.
:scale
Font size scale factor.
:fallback
Whether fallback is enabled.
:letter-spacing
Letter spacing.
:underline-color
Underline colo.
:strikethrough-color
Strikethrough color.
:absolute-size
Font size in pixels scaled by the pango:+scale+ value.
:gravity
Base text gravity.
:gravity-hint
Gravity hint.
:font-features
OpenType font features.
:foreground-alpha
Foreground alpha.
:background-alpha
Background alpha.
:allow-breaks
Whether breaks are allowed. Since 1.44
:show
How to render invisible characters. Since 1.44
:insert-hyphens
Whether to insert hyphens at intra-word line breaks. Since 1.44
:overline
Whether the text has an overline. Since 1.46
:overline-color
Overline color. Since 1.46
:line-height
Line height factor. Since 1.50
:absolute-line-height
Line height. Since 1.50
:text-transform
How Pango treats characters during shaping. Since 1.50
:word
Override segmentation to classify the range of the attribute as a single word. Since 1.50
:sentence
Override segmentation to classify the range of the attribute as a single sentence. Since 1.50
:baseline-shift
Baseline displacement. Since 1.50
:font-scale
Font-relative size change. Since 1.50
Details:
The pango:attr-type enumeration distinguishes between different types of attributes. Along with the predefined values, it is possible to allocate additional values for custom attributes using the pango:attr-type-register function.
See also:
2025-1-1
GEnum pango:underline
Declaration:
(gobject:define-genum "PangoUnderline" underline
  (:export t
   :type-initializer "pango_underline_get_type")
  (:none 0)
  (:single 1)
  (:double 2)
  (:low 3)
  (:error 4)
  (:single-line 5)
  (:double-line 6)
  (:error-line 7))  
Values:
:none
No underline should be drawn.
:single
A single underline should be drawn.
:double
A double underline should be drawn.
:low
A single underline should be drawn at a position beneath the ink extents of the text being underlined. This should be used only for underlining single characters, such as for keyboard accelerators. The :single value should be used for extended portions of text.
:error
A wavy underline should be drawn below. This underline is typically used to indicate an error such as a possible mispelling. In some cases a contrasting color may automatically be used.
:single-line
Like the :single value, but drawn continuously across multiple runs. Since 1.46
:double-line
Like the :double value, but drawn continuously across multiple runs. Since 1.46
:error-line
Like the :error value, but drawn continuously across multiple runs. Since 1.46
Details:
The pango:underline enumeration is used to specify whether text should be underlined, and if so, the type of underlining.
See also:
2025-1-1
GEnum pango:overline
Declaration:
(gobject:define-genum "PangoOverline" overline
  (:export t
   :type-initializer "pango_overline_get_type")
  (:none 0)
  (:single 1))  
Values:
:none
No overline should be drawn.
:single
Draw a single line above the ink extents of the text being overlined.
Details:
The pango:overline enumeration is used to specify whether text should be overlined, and if so, the type of line. Since 1.46
See also:
2025-1-1
GFlags pango:show-flags
Declaration:
(gobject:define-gflags "PangoShowFlags" show-flags
  (:export t
   :type-initializer "pango_show_flags_get_type")
  (:none 0)
  (:spaces #.(ash 1 0))
  (:line-breaks #.(ash 1 1))
  (:ignorables #.(ash 1 2)))  
Values:
:none
No special treatment for invisible characters.
:spaces
Render spaces, tabs and newlines visibly.
:line-breaks
Render line breaks visibly.
:ignorables
Render default-ignorable Unicode characters visibly.
Details:
These flags affect how Pango treats characters that are normally not visible in the output.
See also:
2025-1-1
GEnum pango:text-transform
Declaration:
(gobject:define-genum "PangoTextTransform" text-transform
  (:export t
   :type-initializer "pango_text_transform_get_type")
  :none
  :lowercase
  :uppercase
  :capitalize)  
Values:
:none
Leave text unchanged.
:lowercase
Display letters and numbers as lowercase.
:uppercase
Display letters and numbers as uppercase.
:capitalize
Display the first character of a word in titlecase.
Details:
An enumeration that affects how Pango treats characters during shaping. Since 1.50
See also:
2025-1-1
GEnum pango:baseline-shift
Declaration:
(gobject:define-genum "PangoBaselineShift" baseline-shift
  (:export t
   :type-initializer "pango_baseline_shift_get_type")
  :none
  :superscript
  :subscript)  
Values:
:none
Leave the baseline unchanged.
:superscript
Shift the baseline to the superscript position, relative to the previous run.
:subscript
Shift the baseline to the subscript position, relative to the previous run.
Details:
An enumeration that affects baseline shifts between runs. Since 1.50
See also:
2025-1-1
GEnum pango:font-scale
Declaration:
(gobject:define-genum "PangoFontScale" font-scale
  (:export t
   :type-initializer "pango_font_scale_get_type")
  :none
  :superscript
  :subscript
  :small-caps)  
Values:
:none
Leave the font size unchanged.
:superscript
Change the font to a size suitable for superscripts.
:subscript
Change the font to a size suitable for subscripts.
:small-caps
Change the font to a size suitable for Small Caps.
Details:
An enumeration that affects font sizes for superscript and subscript positioning and for (emulated) Small Caps. Since 1.50
See also:
2025-1-1
GBoxed pango:attribute
Declaration:
(glib:define-gboxed-opaque attribute "PangoAttribute"
   :export t
   :type-initializer "pango_attribute_get_type"
   :alloc (error "PangoAttribute cannot be created from the Lisp side"))  
Returned by:
Slot Access Functions:
Details:
The pango:attribute structure represents the common portions of all attributes. Particular types of attributes include this structure as their initial portion. The common portion of the attribute holds the range to which the value in the type specific part of the attribute applies. By default an attribute will have an all inclusive range of [0,G_MAXUINT].
See also:
2025-1-1
Accessor pango:attribute-start-index (attribute)
Syntax:
(pango:attribute-start-index attribute) => index
(setf (pango:attribute-start-index attribute) index)
Arguments:
attribute -- a pango:attribute instance
index -- an integer for the start index
Details:
Accessor of the start-index slot of the pango:attribute structure.
See also:
2025-1-1
Accessor pango:attribute-end-index (attribute)
Syntax:
(pango:attribute-end-index attribute) => index
(setf (pango:attribute-end-index attribute) index)
Arguments:
attribute -- a pango:attribute instance
index -- an integer for the end index
Details:
Accessor of the end-index slot of the pango:attribute structure.
See also:
2025-1-1
Accessor pango:attribute-type (attribute)
Syntax:
(pango:attribute-type attribute) => type
Arguments:
attribute -- a pango:attribute instance
type -- a pango:attr-type value
Details:
Accessor of the type slot of the pango:attribute structure.
See also:
2025-1-1
Function pango:attribute-copy (attribute)
Arguments:
attribute -- a pango:attribute instance
Returns:
The newly allocated pango:attribute instance.
Details:
Makes a copy of an attribute.
See also:
2025-1-1
Function pango:attribute-equal (attr1 attr2)
Arguments:
attr1 -- a pango:attribute instance
attr2 -- a pango:attribute instance
Returns:
True if the two attributes have the same value.
Details:
Compare two attributes for equality. This compares only the actual value of the two attributes and not the ranges that the attributes apply to.
See also:
2025-1-1
Function pango:attr-type-register (name)
Arguments:
name -- a string for an identifier for the attribute type
Returns:
The integer with the new type ID.
Details:
Allocates a new attribute type ID. The attribute type name can be accessed later by using the pango:attr-type-name function.
See also:
2025-1-1
Function pango:attr-type-name (type)
Arguments:
type -- an integer for an attribute type ID to fetch the name for
Returns:
The string for the type ID name, or nil if type is a built-in Pango attribute type or invalid.
Details:
Fetches the attribute type name passed in when registering the type using the pango:attr-type-register function. The returned value is an interned string that should not be modified.
See also:
2025-1-1
Function pango:attr-language-new (language)
Arguments:
language -- a pango:language instance
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new language tag attribute.
See also:
2025-1-1
Function pango:attr-family-new (family)
Arguments:
family -- a string for the family or comma separated list of families
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font family attribute.
See also:
2025-1-1
Function pango:attr-style-new (style)
Arguments:
style -- a pango:style value for the slant style
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font slant style attribute.
See also:
2025-1-1
Function pango:attr-variant-new (variant)
Arguments:
variant -- a pango:variant value for the variant
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font variant attribute (normal or small caps).
See also:
2025-1-1
Function pango:attr-stretch-new (stretch)
Arguments:
stretch -- a pango:stretch value for the stretch
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font stretch attribute.
See also:
2025-1-1
Function pango:attr-weight-new (weight)
Arguments:
weight -- a pango:weight value for the weight
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font weight attribute.
See also:
2025-1-1
Function pango:attr-size-new (size)
Arguments:
size -- an integer for the font size, in pango:+scale+ units of a point
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font-size attribute in fractional points.
See also:
2025-1-1
Function pango:attr-size-new-absolute (size)
Arguments:
size -- an integer for the font size, in pango:+scale+ units of device units
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new font-size attribute in device units.
See also:
2025-1-1
Function pango:attr-font-desc-new (desc)
Arguments:
desc -- a pango:font-description instance
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.
See also:
2025-1-1
Function pango:attr-foreground-new (red green blue)
Arguments:
red -- an integer for the red value, ranging from 0 to 65535
green -- an integer for the green value
blue -- an integer for the blue value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new foreground color attribute.
See also:
2025-1-1
Function pango:attr-background-new (red green blue)
Arguments:
red -- an integer for the red value, ranging from 0 to 65535
green -- an integer for the green value
blue -- an integer for the blue value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new background color attribute.
See also:
2025-1-1
Function pango:attr-strikethrough-new (strikethrough)
Arguments:
strikethrough -- true if the text should be struck-through
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new strikethrough attribute.
See also:
2025-1-1
Function pango:attr-strikethrough-color-new (red green blue)
Arguments:
red -- an integer for the red value, ranging from 0 to 65535
green -- an integer for the green value
blue -- an integer for the blue value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.
See also:
2025-1-1
Function pango:attr-underline-new (underline)
Arguments:
underline -- a pango:underline value for the underline style
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new underline style attribute.
See also:
2025-1-1
Function pango:attr-underline-color-new (red green blue)
Arguments:
red -- an integer for the red value, ranging from 0 to 65535
green -- an integer for the green value
blue -- an integer for the blue value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color.
See also:
2025-1-1
Function pango:attr-overline-new (overline)
Arguments:
overline -- a pango:overline value for the overline style
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new overline style attribute.

Since 1.46
See also:
2025-1-1
Function pango:attr-overline-color-new (red green blue)
Arguments:
red -- an integer for the red value, ranging from 0 to 65535
green -- an integer for the green value
blue -- an integer for the blue value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new overline color attribute. This attribute modifies the color of overlines. If not set, overlines will use the foreground color.

Since 1.46
See also:
2025-1-1
Function pango:attr-shape-new (ink logical)
Arguments:
ink -- a pango:rectangle instance to assign to each character
logical -- a pango:rectangle instance to assign to each character
Returns:
The newly allocated pango:attribute instance.
Details:
Creates a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a Pango layout.
See also:
2025-1-1
Function pango:attr-scale-new (factor)
Arguments:
factor -- a number coerced to a double float for the factor to scale the font
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new font size scale attribute. The base font for the affected text will have its size multiplied by factor.
See also:
2025-1-1
Function pango:attr-rise-new (rise)
Arguments:
rise -- an integer for the amount that the text should be displaced vertically, in Pango units, positive values displace the text upwards
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new baseline displacement attribute.
See also:
2025-1-1
Function pango:attr-letter-spacing-new (spacing)
Arguments:
spacing -- an integer for the amount of extra space to add between graphemes of the text, in Pango units
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new letter spacing attribute.
See also:
2025-1-1
Function pango:attr-fallback-new (fallback)
Arguments:
fallback -- true if we should fall back on other fonts for characters the active font is missing
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new font fallback attribute. If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text.
See also:
2025-1-1
Function pango:attr-gravity-new (gravity)
Arguments:
gravity -- a pango:gravity value, should not be :auto
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new gravity attribute.
See also:
2025-1-1
Function pango:attr-gravity-hint-new (hint)
Arguments:
hint -- a pango:gravity-hint value
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new gravity hint attribute.
See also:
2025-1-1
Function pango:attr-font-features-new (features)
Arguments:
features -- a string for OpenType font features, in CSS syntax
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new font features tag attribute.
See also:
2025-1-1
Function pango:attr-foreground-alpha-new (alpha)
Arguments:
alpha -- an unsigned integer for the alpha value, between 1 and 65536
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new foreground alpha attribute.
See also:
2025-1-1
Function pango:attr-background-alpha-new (alpha)
Arguments:
alpha -- an unsigned integer for the alpha value, between 1 and 65536
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new background alpha attribute.
See also:
2025-1-1
Function pango:attr-allow-breaks-new (allow)
Arguments:
allow -- true if line breaks are allowed
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new allow breaks attribute. If breaks are disabled, the range will be kept in a single run, as far as possible.

Since 1.44
See also:
2025-1-1
Function pango:attr-insert-hyphens-new (insert)
Arguments:
hyphens -- true if hyphens should be inserted
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new insert hyphens attribute. Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used to suppress the hyphen.

Since 1.44
See also:
2025-1-1
Function pango:attr-show-new (flags)
Arguments:
flags -- a pango:show-flags value to apply.
Returns:
The newly allocated pango:attribute instance.
Details:
Create a new attribute that influences how invisible characters are rendered.

Since 1.44
See also:
2025-1-1
GBoxed pango:attr-list
Declaration:
(glib:define-gboxed-opaque attr-list "PangoAttrList"
  :type-initializer "pango_attr_list_get_type"
  :alloc (%attr-list-new))  
Returned by:
Details:
The pango:attr-list structure represents a list of attributes that apply to a section of text. The pango:attr-list structure is opaque, and has no user visible fields. The attributes are, in general, allowed to overlap in an arbitrary fashion, however, if the attributes are manipulated only through the pango:attr-list-change function, the overlap between properties will meet stricter criteria.

Since the pango:attr-list structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text. In general, you should not use a single pango:attr-list instance for more than one paragraph of text.
See also:
2025-1-1
Function pango:attr-list-new ()
Returns:
The newly allocated pango:attr-list instance.
Details:
Create a new empty attribute list.
See also:
2025-1-1
Function pango:attr-list-copy (attrlist)
Arguments:
attrlist -- a pango:attr-list instance, may be nil
Returns:
The newly allocated pango:attr-list instance. Returns nil if attr-list is nil.
Details:
Copy attrlist and return an identical new attribute list.
See also:
2025-1-1
Function pango:attr-list-equal (attrlist1 attrlist2)
Arguments:
attrlist1 -- a pango:attr-list instance
attrlist2 -- a pango:attr-list instance
Details:
Checks whether listattr1 and listattr2 contain the same attributes and whether those attributes apply to the same ranges. Beware that this will return wrong values if any list contains duplicates.

Since 1.46
See also:
2025-1-1
Function pango:attr-list-insert (attrlist attribute)
Arguments:
attrlist -- a pango:attr-list instance
attribute -- a pango:attribute instance
Details:
Insert the given attribute into the pango:attr-list instance. It will be inserted after all other attributes with a matching start index.
See also:
2025-1-1
Function pango:attr-list-insert-before (attrlist attribute)
Arguments:
attrlist -- a pango:attr-list instance
attribute -- a pango:attribute instance to insert
Details:
Insert the given attribute into the pango:attr-list instance. It will be inserted before all other attributes with a matching start index.
See also:
2025-1-1
Function pango:attr-list-change (attrlist attribute)
Arguments:
attrlist -- a pango:attr-list instance
attribute -- a pango:attribute instance
Details:
Insert the given attribute into the pango:attr-list instance. It will replace any attributes of the same type on that segment and be merged with any adjoining attributes that are identical.

This function is slower than the pango:attr-list-insert function for creating a attribute list in order, potentially much slower for large lists. However, the pango:attr-list-insert function is not suitable for continually changing a set of attributes since it never removes or combines existing attributes.
See also:
2025-1-1
Function pango:attr-list-splice (attrlist1 attrlist2 pos len)
Arguments:
attrlist1 -- a pango:attr-list instance
attrlist2 -- a pango:attr-list instance
pos -- an integer for the position in the attribute list at which to insert attrlist2
len -- an integer for the length of the spliced segment, note that this must be specified since the attributes in attrlist2 may only be present at some subsection of this range
Details:
This function opens up a hole in the attribute list, fills it in with attributes from the left, and then merges attrlist2 on top of the hole. This operation is equivalent to stretching every attribute that applies at position pos in the attribute list by an amount len, and then calling the pango:attr-list-change function with a copy of each attribute in attrlist2 in sequence, offset in position by pos.

This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer.
See also:
#2025-1-1
Callback pango:attr-filter-func
Syntax:
lambda (attribute) => result
Arguments:
attribute -- a pango:attribute instance
result -- a boolean whether the attribute should be filtered out
Details:
A predicate callback function used by the pango:attr-list-filter function to filter out a subset of attributes for an attribute list.
See also:
#2025-1-1
Function pango:attr-list-filter (attrlist func)
Arguments:
attrlist -- a pango:attr-list instance
func -- a pango:attr-filter-func callback function, returns true if an attribute should be filtered out
Returns:
The new pango:attr-list instance or nil if no attributes of the given types were found.
Details:
Given a attribute list and callback function, removes any elements of the attribute list for which func returns true and inserts them into a new attribute list.
See also:
#2025-1-1
Function pango:attr-list-update (attrlist pos remove add)
Arguments:
attrlist -- a pango:attr-list instance
pos -- an integer for the position of the change
remove -- an integer for the number of removed bytes
add -- an integer for the number of added bytes
Details:
Update indices of attributes in the attribute list for a change in the text they refer to. The change that this function applies is removing remove bytes at position pos and inserting add bytes instead.

Attributes that fall entirely in the (pos, pos + remove) range are removed. Attributes that start or end inside the (pos, pos + remove) range are shortened to reflect the removal. Attributes start and end positions are updated if they are behind pos + remove.

Since 1.44
See also:
#2025-1-1
Function pango:attr-list-attributes (attrlist)
Arguments:
attrlist -- a pango:attr-list instance
Returns:
The list of all pango:attribute instances in attrlist.
Details:
Gets a list of all attributes in attrlist.

Since 1.44
See also:
2025-1-1
Function pango:attr-list-from-string (text)
Arguments:
text -- a string for the data
Returns:
The newly created pango:attr-list instance.
Details:
Deserializes a pango:attr-list instance from a string. This is the counterpart to the pango:attr-list-to-string function. See that function for details about the format.

Since 1.50
See also:
2025-1-1
Function pango:attr-list-to-string (attrlist)
Arguments:
attrlist -- a pango:attr-list instance
Returns:
The string with the serialized attributes.
Details:
Serializes a pango-attr-list instance to a string. In the resulting string, serialized attributes are separated by newlines or commas. Individual attributes are serialized to a string of the form
START END TYPE VALUE  
Where START and END are the indices, with -1 being accepted in place of MAXUINT, TYPE is the nickname of the attribute value type, for example weight or stretch, and the value is serialized according to its type:
  • enum values as nick or numeric value
  • boolean values as true or false
  • integers and floats as numbers
  • strings as string, optionally quoted
  • font features as quoted string
  • Pango language as string
  • Pango font description as serialized by the pango:font-description-to-string function
  • pango:color instances as serialized by the pango:color-to-string function
To parse the returned value, use the pango:attr-list-from-string function.

Note that shape attributes can not be serialized.
Examples:
0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10"
0 -1 weight 700
0 100 family Times    
Since 1.50
See also:
2025-1-1
Function pango:attr-list-iterator (attrlist)
Arguments:
attrlist -- a pango:attr-list instance
Returns:
The pango:attr-iterator instance.
Details:
Create an iterator initialized to the beginning of the attribute list. The attrlist argument must not be modified until this iterator is freed.
See also:
2025-1-1
GBoxed pango:attr-iterator
Declaration:
(glib:define-gboxed-opaque attr-iterator "PangoAttrIterator"
  :export t
  :type-initializer "pango_attr_iterator_get_type"
  :alloc (error "PangoAttrIterator cannot be created from the Lisp side."))  
Returned by:
Details:
The pango:attr-iterator structure is used to represent an iterator through a pango:attr-list instance. The pango:attr-iterator structure is opaque, and has no user visible fields. A new iterator is created with the pango:attr-list-iterator function. Once the iterator is created, it can be advanced through the style changes in the text using the pango:attr-iterator-next function. At each style change, the range of the current style segment and the attributes currently in effect can be queried.
See also:
2025-1-1
Function pango:attr-iterator-copy (iterator)
Arguments:
iterator -- a pango:attr-iterator instance
Returns:
The newly allocated pango:attr-iterator instance.
Details:
Copy a pango:attr-iterator instance.
See also:
2025-1-1
Function pango:attr-iterator-next (iterator)
Arguments:
iterator -- a pango:attr-iterator instance
Returns:
False if the iterator is at the end of the attribute list, otherwise true.
Details:
Advance the iterator until the next change of style.
See also:
2025-1-1
Function pango:attr-iterator-range (iterator)
Arguments:
iterator -- a pango:attr-iterator instance
Returns:
start -- an integer with the start range
end -- an integer with the end range
Details:
Get the range of the current segment. Note that the stored return values are signed, not unsigned like the values in the pango:attribute instance. To deal with this API oversight, stored return values that would not fit into a signed integer are clamped to G_MAXINT.
See also:
2025-1-1
Function pango:attr-iterator-get (iterator type)
Arguments:
iterator -- a pango:attr-iterator instance
type -- a pango:attr-type value for the type of attribute to find
Returns:
The current pango:attribute instance of the given type, or nil if no attribute of that type applies to the current location.
Details:
Find the current attribute of a particular type at the iterator location. When multiple attributes of the same type overlap, the attribute whose range starts closest to the current location is used.
See also:
2025-1-1
Function pango:attr-iterator-font (iterator)
Syntax:
(pango:attr-iterator-font iterator) => desc, language, attrs
Arguments:
iterator -- a pango:attr-iterator instance
desc -- a pango:font-description instance for the current values
language -- a pango:language instance with the language tag at the current position, or nil if none is found
attrs -- a list of pango:attribute instances with non-font attributes at the the current position, only the highest priority value of each attribute will be added to this list
Details:
Get the font and other attributes at the current iterator position.
See also:
2025-1-1
Function pango:attr-iterator-attrs (iterator)
Arguments:
iterator -- a pango:attr-iterator instance
Returns:
The list of all pango:attribute instances for the current range.
Details:
Gets a list of all attributes at the current position of the iterator.
See also:
2025-1-1

Pango Markup

Simple markup language for text with attributes.

Frequently, you want to display some text to the user with attributes applied to part of the text. For example, you might want bold or italicized words. With the base Pango interfaces, you could create a pango:attr-list instance and apply it to the text. The problem is that you would need to apply attributes to some numeric range of characters, for example "characters 12-17." This is broken from an internationalization standpoint. Once the text is translated, the word you wanted to italicize could be in a different position.

The solution is to include the text attributes in the string to be translated. Pango provides this feature with a small markup language. You can parse a marked-up string into the string text plus a pango:attr-list instance using the pango:parse-markup function.

A simple example of a marked-up string might be:
<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!      
Pango uses GMarkup to parse this language, which means that XML features such as numeric character entities such as &amp;#169; for © can be used too.

The root tag of a marked-up document is <markup>, but the pango:parse-markup function allows you to omit this tag, so you will most likely never need to use it. The most general markup tag is <span>, then there are some convenience tags.

Span attributes
<span> has the following attributes:
font_desc
A font description string, such as "Sans Italic 12". See the pango:font-description-from-string function for a description of the format of the string representation. Note that any other span attributes will override this description. So if you have "Sans Italic" and also a style="normal" attribute, you will get Sans normal, not italic.
font_family
A font family name.
font_size, size
Font size in 1024ths of a point, or one of the absolute sizes xx-small, x-small, small, medium, large, x-large, xx-large, or one of the relative sizes smaller or larger. If you want to specify a absolute size, it is usually easier to take advantage of the ability to specify a partial font description using font. You can use font='12.5' rather than size='12800'.
font_style
One of normal, oblique, italic.
font_weight
One of ultralight, light, normal, bold, ultrabold, heavy, or a numeric weight.
font_variant
One of normal or smallcaps.
font_stretch, stretch
One of ultracondensed, extracondensed, condensed, semicondensed, normal, semiexpanded, expanded, extraexpanded, ultraexpanded.
font_features
A comma-separated list of OpenType font feature settings, in the same syntax as accepted by CSS, e.g. font_features='dlig=1, -kern, afrc on'.
foreground, fgcolor
An RGB color specification such as #00FF00 or a color name such as red. An RGBA color specification such as #00FF007F will be interpreted as specifying both a foreground color and foreground alpha.
background, bgcolor
An RGB color specification such as #00FF00 or a color name such as red. An RGBA color specification such as #00FF007F will be interpreted as specifying both a background color and background alpha.
alpha, fgalpha
An alpha value for the foreground color, either a plain integer between 1 and 65536 or a percentage value like 50 %.
background_alpha, bgalpha
An alpha value for the background color, either a plain integer between 1 and 65536 or a percentage value like 50 %.
underline
One of none, single, double, low, error, single-line, double-line or error-line.
underline_color
The color of underlines. An RGB color specification such as #00FF00 or a color name such as red.
overline
One of none or single.
overline_color
The color of overlines. An RGB color specification such as #00FF00 or a color name such as red.
rise
Vertical displacement, in Pango units. Can be negative for subscript, positive for superscript.
strikethrough
True or false whether to strike through the text.
strikethrough_color
The color of strikethrough lines. An RGB color specification such as #00FF00 or a color name such as red.
fallback
True or false whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
allow_breaks
True or false whether to allow line breaks or not. If not allowed, the range will be kept in a single run as far as possible. Breaks are allowed by default.
insert_hyphens
True or false whether to insert hyphens when breaking lines in the middle of a word. Hyphens are inserted by default.
show
A value determining how invisible characters are treated. Possible values are spaces, line-breaks, ignorables or combinations, such as spaces and line-breaks.
lang
A language code, indicating the text language.
letter_spacing
Inter-letter spacing in 1024ths of a point.
gravity
One of south, east, north, west, auto.
gravity_hint
One of natural, strong, line.
Convenience tags
The following convenience tags are provided:
<b>
Bold.
<big>
Makes font relatively larger, equivalent to <span size="larger">.
<i>
Italic.
<s>
Strikethrough.
<sub>
Subscript.
<sup>
Superscript.
<small>
Makes font relatively smaller, equivalent to <span size="smaller">.
<tt>
Monospace.
<u>
Underline.
Function pango:parse-markup (markup marker)
Arguments:
markup -- a string with the parkup to parse
marker -- a character that precedes an accelerator, or 0 for none
Returns:
text -- a string with the text with tags stripped
attrlist -- a pango:attr-list instance
char -- a character with the accelerator char
Details:
Parses marked-up text to create a plain-text string and an attribute list. If marker is nonzero, the given character will mark the character following it as an accelerator. For example, marker might be an ampersand or underscore. All characters marked as an accelerator will receive a :underline-low attribute, and the first character so marked will be returned in char. Two marker characters following each other produce a single literal marker character.

If any error happens, nil is returned.
Examples:
(multiple-value-bind (text attrlist char)
    (pango:parse-markup "<b>_Text</b>" #\_)
  (values text
          (pango:attr-list-to-string attrlist)
          char))
=> "Text"
   "0 1 underline low
    0 4 weight bold"
   #\T

(multiple-value-bind (text attrlist char) (pango:parse-markup "<span foreground='blue' size='x-large'> Blue text </span> is <i>cool</i>!" #\_) (values text (pango:attr-list-to-string attrlist) char)) => "Blue text is cool!" "0 9 scale 1.440000 0 9 foreground #00000000ffff 13 17 style italic" #\Nul
See also:
2024-11-21

Layout Objects

While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. The objects and functions in this section provide a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line-breaking, justification, alignment and ellipsization.

Types and functions for PangoLayout

GEnum pango:wrap-mode
Declaration:
(gobject:define-genum "PangoWrapMode" wrap-mode
  (:export t
   :type-initializer "pango_wrap_mode_get_type")
  (:word 0)
  (:char 1)
  (:word-char 2)
  #+pango-1-56
  (:none 3))  
Values:
:word
Wrap lines at word boundaries.
:char
Wrap lines at character boundaries.
:word-char
Wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.
:none
Do not wrap.
Details:
The pango:wrap-mode enumeration describes how to wrap the lines of a pango:layout object to the desired width. For the :wrap-word value, Pango uses break opportunities that are determined by the Unicode line breaking algorithm. For the :wrap-char value, Pango allows breaking at grapheme boundaries that are determined by the Unicode text segmentation algorithm.
See also:
2025-3-28
GEnum pango:ellipsize-mode
Declaration:
(gobject:define-genum "PangoEllipsizeMode" ellipsize-mode
  (:export t
   :type-initializer "pango_ellipsize_mode_get_type")
  (:none 0)
  (:start 1)
  (:middle 2)
  (:end 3))  
Values:
:none
No ellipsization.
:start
Omit characters at the start of the text.
:middle
Omit characters in the middle of the text.
:end
Omit characters at the end of the text.
Details:
The pango:ellipsize-mode enumeration describes what sort of (if any) ellipsization should be applied to a line of text. In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis.
See also:
2025-2-18
GEnum pango:alignment
Declaration:
(gobject:define-genum "PangoAlignment" alignment
  (:export t
   :type-initializer "pango_alignment_get_type")
  (:left 0)
  (:center 1)
  (:right 2))  
Values:
:left
Put all available space on the right.
:center
Center the line within the available space.
:right
Put all available space on the left.
Details:
The pango:alignment enumeration describes how to align the lines of a pango:layout object within the available space. If the pango:layout object is set to justify using the pango:layout-justify function, this only has effect for partial lines.
See also:
2025-2-18
Class pango:layout
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The pango:layout class represents an entire paragraph of text. It is initialized with a pango:context object, UTF-8 string and set of attributes for that string. Once that is done, the set of formatted lines can be extracted from the pango:layout object. The Pango layout can be rendered, and conversion between logical character positions within the text of the Pango layout, and the physical position of the resulting glyphs can be made.

There are also a number of parameters to adjust the formatting of a Pango layout. It is possible, as well, to ignore the 2-D setup, and simply treat the results of a Pango layout as a list of lines.

Figure: Adjustable parameters (on the left) and font metrics (on the right) for a Pango layout

See also:
2025-2-18
Function pango:layout-new (context)
Arguments:
context -- a pango:context object
Returns:
The newly allocated pango:layout object.
Details:
Create a new Pango layout with attributes initialized to default values for a particular pango:context object.
See also:
2025-2-15
Function pango:layout-copy (src)
Arguments:
src -- a pango:layout object
Returns:
The newly allocated pango:layout object with the copy of src.
Details:
Does a deep copy-by-value of the Pango layout. The attribute list, tab array, and text from the original Pango layout are all copied by value.
See also:
2025-2-15
Function pango:layout-context (layout)
Arguments:
layout -- a pango:layout object
Returns:
The pango:context object for layout.
Details:
Retrieves the Pango context used for this Pango layout.
See also:
2025-2-15
Function pango:layout-context-changed (layout)
Arguments:
layout -- a pango:layout object
Details:
Forces recomputation of any state in the Pango layout that might depend on the Pango context of layout. This function should be called if you make changes to the Pango context subsequent to creating the Pango layout.
See also:
2025-2-15
Function pango:layout-serial (layout)
Arguments:
layout -- a pango:layout object
Returns:
The unsigned integer with the current serial number of layout.
Details:
Returns the current serial number of the Pango layout. The serial number is initialized to an small number larger than zero when a new Pango layout is created and is increased whenever the Pango layout is changed using any of the setter functions, or the pango:context object it uses has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals".

This can be used to automatically detect changes to a Pango layout, and is useful, for example, to decide whether a Pango layout needs redrawing. To force the serial to be increased, use the pango:layout-context-changed function.
See also:
2025-2-15
Function pango:layout-text (layout)
Syntax:
(pango:layout-text layout) => text
(setf (pango:layout-text layout) text)
Arguments:
layout -- a pango:layout object
text -- a valid UTF-8 string
Details:
The pango:layout-text function gets the text in the Pango layout. The (setf pango:layout-text) function sets the text.

Note that if you have used the pango:layout-set-markup or pango:layout-set-markup-with-accel functions on the Pango layout before, you may want to call the pango:layout-attributes function to clear the attributes set on the Pango layout from the markup as this function does not clear attributes.
See also:
2025-2-15
Function pango:layout-character-count (layout)
Arguments:
layout -- a pango:layout object
Returns:
The integer with the number of Unicode characters in the text of layout.
Details:
Returns the number of Unicode characters in the text of the Pango layout.
See also:
2025-2-15
Function pango:layout-set-markup (layout markup)
Arguments:
layout -- a pango:layout object
markup -- a string for the marked-up text
Details:
Same as the pango:layout-set-markup-with-accel function, but the markup text is not scanned for accelerators.
See also:
2025-2-15
Function pango:layout-set-markup-with-accel (layout markup marker)
Arguments:
layout -- a pango:layout object
markup -- a string for the marked-up text
marker -- a character or an integer with the char code for the marker for accelerators in the text
Returns:
The character with the first located accelerator.
Details:
Sets the layout text and attribute list from marked-up text (see markup format). Replaces the current text and attribute list.

If marker is nonzero, the given character will mark the character following it as an accelerator. For example, marker might be an ampersand or underscore. All characters marked as an accelerator will receive a :low attribute of the pango:underline enumeration, and the first character so marked will be returned. Two marker characters following each other produce a single literal marker character.
See also:
2025-2-15
Function pango:layout-attributes (layout)
Syntax:
(pango:layout-attributes layout) => attrs
(setf (pango:layout-attributes layout) attrs)
Arguments:
layout -- a pango:layout object
attrs -- a pango:attr-list instance, can be nil
Details:
The pango:layout-attributes function gets the attribute list for the Pango layout, if any. The (setf pango:layout-attributes) function sets the text attributes.
See also:
2025-2-15
Function pango:layout-font-description (layout)
Syntax:
(pango:layout-font-description layout) => desc
(setf (pango:layout-font-description layout) desc)
Arguments:
layout -- a pango:layout object
desc -- a pango:font-description instance, or nil to unset the current font description
Details:
The pango:layout-font-description function gets the font description for the Pango layout. The (setf pango:layout-font-description) function sets the default font description.

If no font description is set on the Pango layout, the font description from the Panto context is used.
See also:
2025-2-15
Function pango:layout-width (layout)
Syntax:
(pango:layout-width layout) => width
(setf (pango:layout-width layout) width)
Arguments:
layout -- a pango:layout object
width -- an integer for the desired width in Pango units, or -1 to indicate that no wrapping or ellipsization should be performed
Details:
The pango:layout-width function gets the width to which the lines of the Pango layout should wrap or ellipsized. The (setf pango:layout-width) function sets the width. The default value is -1 for no width is set.
See also:
2025-2-15
Function pango:layout-height (layout)
Syntax:
(pango:layout-height layout) => height
(setf (pango:layout-height layout) height)
Arguments:
layout -- a pango:layout object
height -- an integer for the desired height of the Pango layout in Pango units if positive, or the desired number of lines if negative
Details:
The pango:layout-height function gets the height of layout used for ellipsization. The (setf pango:layout-height) function sets the height to which the Pango layout should be ellipsized at. There are two different behaviors, based on whether height is positive or negative.

If height is positive, it will be the maximum height of the Pango layout. Only lines would be shown that would fit, and if there is any text omitted, an ellipsis is added. At least one line is included in each paragraph regardless of how small the height value is. A value of zero will render exactly one line for the entire Pango layout.

If height is negative, it will be the (negative of) maximum number of lines per paragraph. That is, the total number of lines shown may well be more than this value if the Pango layout contains multiple paragraphs of text. The default value of -1 means that first line of each paragraph is ellipsized. This behvaior may be changed in the future to act per Pango layout instead of per paragraph. File a bug against pango at http://bugzilla.gnome.org/ if your code relies on this behavior.

Height setting only has effect if a positive width is set on the Pango layout and the ellipsization mode of the Pango layout is not :none. The behavior is undefined if a height other than -1 is set and the ellipsization mode is set to :none, and may change in the future.
See also:
2025-2-15
Function pango:layout-wrap (layout)
Syntax:
(pango:layout-wrap layout) => wrap
(setf (pango:layout-wrap layout) wrap)
Arguments:
layout -- a pango:layout object
wrap -- a value of the pango:wrap-mode enumeration
Details:
The pango:layout-wrap function gets the wrap mode for the Pango layout. The (setf pango:layout-wrap) function sets the wrap mode. The wrap mode only has effect if a width is set on the Pango layout with the pango:layout-width function. To turn off wrapping, set the width to -1.

Use the pango:layout-is-wrapped function to query whether any paragraphs were actually wrapped.
See also:
#2025-2-15
Function pango:layout-is-wrapped (layout)
Arguments:
layout -- a pango:layout object
Returns:
True if any paragraphs had to be wrapped, false otherwise.
Details:
Queries whether the Pango layout had to wrap any paragraphs. This returns true if a positive width is set on the Pango layout, the ellipsization mode of the Pango layout is set to :none, and there are paragraphs exceeding the Pango layout width that have to be wrapped.
See also:
#2025-2-15
Function pango:layout-ellipsize (layout)
Syntax:
(pango:layout-ellipsize layout) => ellipsize
(setf (pango:layout-ellipsize layout) ellipsize)
Arguments:
layout -- a pango:layout object
ellipsize -- a value of the pango:ellipsize-mode enumeration
Details:
The pango:layout-ellipsize function gets the type of ellipsization being performed for the Pango layout. The (setf pango:layout-ellipsize) function sets the type of ellipsization. Depending on the ellipsization mode ellipsize text is removed from the start, middle, or end of the text so they fit within the width and height of Pango layout set with the pango:layout-width and pango:layout-height functions.

If the Pango layout contains characters such as newlines that force it to be layed out in multiple paragraphs, then whether each paragraph is ellipsized separately or the entire Pango layout is ellipsized as a whole depends on the set height of the Pango layout. See the pango:layout-height function for details.

Use the pango:layout-is-ellipsized function to query whether any paragraphs were actually ellipsized.
See also:
#2025-2-15
Function pango:layout-is-ellipsized (layout)
Arguments:
layout -- a pango:layout object
Returns:
True if any paragraphs had to be ellipsized, false otherwise.
Details:
Queries whether the Pango layout had to ellipsize any paragraphs. This returns true if the ellipsization mode for the Pango layout is not :none, a positive width is set on the Pango layout, and there are paragraphs exceeding that width that have to be ellipsized.
See also:
#2025-2-15
Function pango:layout-indent (layout)
Syntax:
(pango:layout-indent layout) => indent
(setf (pango:layout-indent layout) indent)
Arguments:
layout -- a pango:layout object
indent -- an integer for the amount by which to indent
Details:
The pango:layout-indent function gets the paragraph indent width in Pango units. The (setf pango:layout-indent) function sets the width in Pango units to indent each paragraph. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent.

The indent setting is ignored if the Pango layout alignment is set to the :center value.
See also:
#2025-2-15
Function pango:layout-spacing (layout)
Syntax:
(pango:layout-spacing layout) => spacing
(setf (pango:layout-spacing layout) spacing)
Arguments:
layout -- a pango:layout object
spacing -- an integer for the amount of spacing
Details:
The pango:layout-spacing function gets the amount of spacing in Pango units between the lines of the Pango layout. The (setf pango:layout-spacing) function sets the amount of spacing. When placing lines with spacing, Pango arranges things so that
line2.top = line1.bottom + spacing  
Notes:
Since 1.44, Pango defaults to using the line height (as determined by the font) for placing lines. The spacing set with this function is only taken into account when the line-height factor is set to zero with the pango:layout-line-spacing function.
See also:
#2025-2-15
Function pango:layout-line-spacing (layout)
Syntax:
(pango:layout-line-spacing layout) => factor
(setf (pango:layout-line-spacing layout) factor)
Arguments:
layout -- a pango:layout object
factor -- a number coerced to a single float for the new line spacing factor
Details:
The pango:layout-line-spacing function gets the value of the line spacing. The (setf pango:layout-line-spacing) function sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2. The default values is 0.

If the factor argument is non-zero, lines are placed so that
baseline2 = baseline1 + factor * height2  
where height2 is the line height of the second line as determined by the font. In this case, the spacing set with the pango:layout-spacing function is ignored.

If the factor argument is zero, spacing is applied as before.

Since 1.44
See also:
2025-2-15
Function pango:layout-justify (layout)
Syntax:
(pango:layout-justify layout) => justify
(setf (pango:layout-justify layout) justify)
Arguments:
layout -- a pango:layout object
justify -- a boolean whether the lines in the Pango layout should be justified
Details:
The pango:layout-justify function gets whether each complete line should be stretched to fill the entire width of the Pango layout. The (setf pango:layout-justify) function sets the justify. This stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification may be done in more complex ways, like extending the characters.
See also:
#2025-2-15
Function pango:layout-auto-dir (layout)
Syntax:
(pango:layout-auto-dir layout) => auto
(setf (pango:layout-auto-dir layout) auto)
Arguments:
layout -- a pango:layout object
auto -- if true, compute the bidirectional base direction from the contents of the Pango layout
Details:
The pango:layout-auto-dir function gets whether to calculate the bidirectional base direction for the Pango layout according to the contents of the Pango layout. The (setf pango:layout-auto-dir) function sets whether to calculate the bidirectional base direction for the Pango layout according to the contents of the Pango layout. When this flag is on (the default), then paragraphs in the Pango layout that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-to-left layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs.

When false, the choice between left-to-right and right-to-left layout is done according to the base direction of the Pango context of the Pango layout, see the pango:context-base-dir function.

When the auto-computed direction of a paragraph differs from the base direction of the Pango context, the interpretation of :left and :right are swapped.
See also:
#2025-2-15
Function pango:layout-direction (layout index)
Arguments:
layout -- a pango:layout object
index -- an integer for the byte index of the char
Returns:
The pango:direction value with the text direction at index.
Details:
Gets the text direction at the given character position in the Pango layout.

Since 1.46
See also:
#2025-2-15
Function pango:layout-alignment (layout)
Syntax:
(pango:layout-alignment layout) => alignment
(setf (pango:layout-alignment layout) alignment)
Arguments:
layout -- a pango:layout object
alignment -- a pango:alignment value
Details:
The pango:layout-alignment function gets the alignment for the Pango layout. That is, how partial lines are positioned within the horizontal space available. The (setf pango:layout-alignment) function sets the alignment.
See also:
#2025-2-15
Function pango:layout-tabs (layout)
Syntax:
(pango:layout-tabs layout) => tabs
(setf (pango:layout-tabs layout) tabs)
Arguments:
layout -- a pango:layout object
tabs -- a pango:tab-array instance, or nil
Details:
The pango:layout-tabs function gets the current pango:tab-array instance used by this Pango layout. The (setf pango:layout-tabs) function sets the tabs to use.

If no pango:tab-array instance has been set, then the default tabs are in use and nil is returned. Default tabs are every 8 spaces.
See also:
#2025-2-15
Function pango:layout-single-paragraph-mode (layout)
Syntax:
(pango:layout-tabs layout) => tabs
(setf (pango:layout-tabs layout) tabs)
Arguments:
layout -- a pango:layout object
setting -- a boolean whether the Pango layout does not break paragraphs at paragraph separator characters
Details:
If setting is true, do not treat newlines and similar characters as paragraph separators. Instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line.
See also:
#2025-2-15
Function pango:layout-unknown-glyphs-count (layout)
Arguments:
layout -- a pango:layout object
Returns:
The integer with the number of unknown glyphs in layout.
Details:
Counts the number of unknown glyphs in the Pango layout. That is, zero if glyphs for all characters in the Pango layout text were found, or more than zero otherwise.

This function can be used to determine if there are any fonts available to render all characters in a certain string, or when used in combination with the :fallback value of the pango:attr-type enumeration, to check if a certain font supports all the characters in the string.
See also:
#2025-2-15
Function pango:layout-index-to-pos (layout index)
Syntax:
(pango:layout-index-to-pos layout index) => x, y, width, height
Arguments:
layout -- a pango:layout object
index -- an integer for the byte index within layout
x -- an integer for the x coordinate
y -- an integer for the y coordinate
width -- an integer for the width
height -- an integer for the height
Details:
Converts from an index within a Pango layout to the onscreen position corresponding to the grapheme at that index, which is represented as the coordinates of a rectangle.

Note that x is always the leading edge of the grapheme and x + width the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then witdh will be negative.
See also:
2025-2-15
Function pango:layout-index-to-line-x (layout index trailing)
Syntax:
(pango:layout-index-to-line-x layout index trailing) => line, xpos
Arguments:
layout -- a pango:layout object
index -- an integer for the byte index of a grapheme within the Pango layout
trailing -- an integer indicating the edge of the grapheme to retrieve the position of, if 0, the trailing edge of the grapheme, if > 0, the leading of the grapheme
line -- an integer with the resulting line index, which will between 0 and (pango:layout-line-count layout) - 1, or nil
xpos -- an integer with the resulting position within line in Pango units per device unit, or nil
Details:
Converts from byte index within the Pango layout to line and xpos position. The xpos position is measured from the left edge of the line.
See also:
2025-2-15
Function pango:layout-xy-to-index (layout x y)
Syntax:
(pango:layout-xy-to-index layout x y) => index, trailing
Arguments:
layout -- a pango:layout object
x -- an integer for the x offset in Pango units from the left edge of the Pango layout
y -- an integer for the y offset in Pango units from the top edge of the Pango layout
index -- an integer with the calculated byte index
trailing -- an integer indicating where in the grapheme the user clicked, it will either be zero, or the number of characters in the grapheme, 0 represents the trailing edge of the grapheme
Details:
Converts from x and y position within a Pango layout to the byte index of the character at that logical position. If the y position is not inside the Pango layout, the closest position is chosen (the position will be clamped inside the Pango layout). If the x position is not within the Pango layout, then the start or the end of the line is chosen as described for the pango:layout-line-x-to-index function. If either the x or y positions were not inside the Pango layout, then the function returns nil.
See also:
2025-2-15
Function pango:layout-cursor-pos (layout index)
Syntax:
(pango:layout-cursor-pos layout index) => strong, weak
Arguments:
layout -- a pango:layout object
index -- an integer for the byte index of the cursor
strong -- a list with the x, y, width, height values of the rectangle for the strong cursor position
weak -- a list with the x, y, width, height values of the rectangle for the weak cursor position
Details:
Given an index within a Pango layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the Pango layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.
See also:
2025-2-15
Function pango:layout-move-cursor-visually (layout strong index trailing direction)
Syntax:
(pango:layout-move-cursor-visually layout strong index trailing direction) => new-index, new-trailing
Arguments:
layout -- a pango:layout object
strong -- a boolean whether the moving cursor is the strong cursor or the weak cursor, the strong cursor is the cursor corresponding to text insertion in the base direction for the layout
index -- an integer for the byte index of the grapheme for the old index
trailing -- an integer, if 0, the cursor was at the trailing edge of the grapheme indicated by index, if > 0, the cursor was at the leading edge
direction -- an integer for the direction to move cursor, a negative value indicates motion to the left
new-index -- an integer for the new cursor byte index, a value of -1 indicates that the cursor has been moved off the beginning of the Pango layout, a value of G_MAXINT indicates that the cursor has been moved off the end of the Pango layout
new-trailing -- an integer for the number of characters to move forward from the location returned for new-index to get the position where the cursor should be displayed, this allows distinguishing the position at the beginning of one line from the position at the end of the preceding line, new-index is always on the line where the cursor should be displayed
Details:
Computes a new cursor position from an old position and a count of positions to move visually. If direction is positive, then the new strong cursor position will be one position to the right of the old cursor position. If direction is negative, then the new strong cursor position will be one position to the left of the old cursor position.

In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run.

Motion here is in cursor positions, not in characters, so a single call to the pango:layout-move-cursor-visually function may move the cursor over multiple characters when multiple characters combine to form a single grapheme.
See also:
2025-2-15
Function pango:layout-extents (layout ink logical)
Arguments:
layout -- a pango:layout object
ink -- a pango:rectangle instance to fill with the extents of the Pango layout as drawn, or nil
logical -- a pango:rectangle instance to fill with the logical extents of the Pango layout, or nil
Details:
Computes the logical and ink extents of the Pango layout. Logical extents are usually what you want for positioning things. Note that both extents may have non-zero x and y parameters for the rectangles. You may want to use those to offset where you render the Pango layout. Not doing that is a very typical bug that shows up as right-to-left Pango layouts not being correctly positioned in a Pango layout with a set width.

The extents are given in Pango layout coordinates and in Pango units. Pango layout coordinates begin at the top left corner of the Pango layout.
See also:
2025-2-15
Function pango:layout-pixel-extents (layout ink logical)
Arguments:
layout -- a pango:layout object
ink -- a pango:rectangle instance to fill with the extents of the Pango layout as drawn, or nil
logical -- a pango:rectangle instance to fill with the logical extents of the Pango layout, or nil
Details:
Computes the logical and ink extents of the Pango layout in device units. This function just calls the pango:layout-extents function followed by two pango:extents-to-pixels function calls, rounding the ink and logical values such that the rounded rectangles fully contain the unrounded one, that is, passes them as first argument to the pango:extents-to-pixels function.
See also:
2025-2-15
Function pango:layout-size (layout)
Syntax:
(pango:layout-size layout) => width, height
Arguments:
layout -- a pango:layout object
width -- an integer for the logical width
height -- an integer for the logical height
Details:
Determines the logical width and height of a Pango layout in Pango units, device units scaled by the pango:+scale+ constant. This is simply a convenience function around the pango:layout-extents function.
See also:
2025-2-15
Function pango:layout-pixel-size (layout)
Syntax:
(pango:layout-pixel-size layout) => width, height
Arguments:
layout -- a pango:layout object
width -- an integer for the logical width
height -- an integer for the logical height
Details:
Determines the logical width and height of a Pango layout in device units. The pango:layout-size function returns the width and height scaled by pango:+scale+. This is simply a convenience function around the pango:layout-pixel-extents function.
See also:
2025-2-15
Function pango:layout-baseline (layout)
Arguments:
layout -- a pango:layout object
Returns:
The integer with the baseline of the first line, from top of layout.
Details:
Gets the y position of the baseline for the first line in the Pango layout.
See also:
2025-2-15
Function pango:layout-line-count (layout)
Arguments:
layout -- a pango:layout object
Returns:
The integer with the line count.
Details:
Retrieves the count of lines for the Pango layout.
See also:
2025-2-15
Function pango:layout-line (layout line)
Arguments:
layout -- a pango:layout object
linenum -- an integer for the index of a line, which must be between 0 and (pango:layout-line-count layout) - 1, inclusive
Returns:
The requested pango:layout-line instance, or nil if the index is out of range. This Pango layout line will become invalid if changes are made to the Pango layout.
Details:
Retrieves a particular line from a Pango layout. Use the faster pango:layout-line-readonly function if you do not plan to modify the contents of the line (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-line-readonly (layout line)
Arguments:
layout -- a pango:layout object
line -- an integer for the index of a line, which must be between 0 and (pango:layout-line-count layout) - 1, inclusive
Returns:
The requested pango:layout-line instance, or nil if the index is out of range. This Pango layout line will become invalid if changes are made to the PangoLayout. No changes should be made to the line.
Details:
Retrieves a particular line from a Pango layout. This is a faster alternative to the pango:layout-line function, but the user is not expected to modify the contents of the line (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-lines (layout)
Arguments:
layout -- a pango:layout object
Returns:
The list containing the pango:layout-line instances in the Pango layout. This points to internal data of the Pango layout and must be used with care. It will become invalid on any change to the text or properties of the Pango layout.
Details:
Returns the lines of the Pango layout as a list. Use the faster pango:layout-lines-readonly function if you do not plan to modify the contents of the lines (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-lines-readonly (layout)
Arguments:
layout -- a pango:layout object
Returns:
The list containing the pango:layout-line instances in the Pango layout. This points to internal data of the Pango layout and must be used with care. It will become invalid on any change to the text or properties of the Pango layout. No changes should be made to the lines.
Details:
Returns the lines of the Pango layout as a list. This is a faster alternative to the pango:layout-lines function, but the user is not expected to modify the contents of the lines (glyphs, glyph widths, and so on).
See also:
2025-2-15

Type and functions for PangoLayoutIter

GBoxed pango:layout-iter
Declaration:
(glib:define-gboxed-opaque layout-iter "PangoLayoutIter"
  :export t
  :type-initializer "pango_layout_iter_get_type"
  :alloc (error "PANGO:LAYOUT-ITER cannot be created from the Lisp side."))  
Returned by:
Details:
The pango:layout-iter structure can be used to iterate over the visual extents of a pango:layout object. The pango:layout-iter structure is opaque, and has no user visible fields.
See also:
2025-2-15
Function pango:layout-iter (layout)
Arguments:
layout -- a pango:layout object
Returns:
The new pango:layout-iter instance.
Details:
Returns an iterator to iterate over the visual extents of the Pango layout.
See also:
2025-2-15
Function pango:layout-iter-copy (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The newly allocated pango:layout-iter instance.
Details:
Copies a Pango layout iterator.
See also:
2025-2-15
Function pango:layout-iter-next-run (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The boolean whether motion was possible.
Details:
Moves iter forward to the next run in visual order. If iter was already at the end of the Pango layout, returns false.
See also:
2025-2-15
Function pango:layout-iter-next-char (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The boolean whether motion was possible.
Details:
Moves iter forward to the next character in visual order. If iter was already at the end of the Pango layout, returns false.
See also:
2025-2-15
Function pango:layout-iter-next-cluster (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The boolean whether motion was possible.
Details:
Moves iter forward to the next cluster in visual order. If iter was already at the end of the Pango layout, returns false.
See also:
2025-2-15
Function pango:layout-iter-next-line (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The boolean whether motion was possible.
Details:
Moves iter forward to the start of the next line. If iter is already on the last line of the Pango layout, returns false.
See also:
2025-2-15
Function pango:layout-iter-at-last-line (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
True if iter is on the last line.
Details:
Determines whether iter is on the last line of the Pango layout.
See also:
2025-2-15
Function pango:layout-iter-index (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The integer with the current byte index.
Details:
Gets the current byte index. Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the Pango layout, if on the NULL run. See the pango:layout-iter-run function.
See also:
2025-2-15
Function pango:layout-iter-baseline (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The integer with the baseline of the current line.
Details:
Gets the y position of the baseline of the current line, in Pango layout coordinates (origin at top left of the entire Pango layout).
See also:
2025-2-15
Function pango:layout-iter-run (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The pango:glyph-item instance with the current run.
Details:
Gets the current run. When iterating by run, at the end of each line, there is a position with a NULL run, so this function can return nil. The NULL run at the end of each line ensures that all lines have at least one run, even lines consisting of only a newline.

Use the faster pango:layout-iter-run-readonly function if you do not plan to modify the contents of the run (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-iter-run-readonly (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The pango:layout-iter instance with the current run, that should not be modified.
Details:
Gets the current run. When iterating by run, at the end of each line, there is a position with a NULL run, so this function can return nil. The NULL run at the end of each line ensures that all lines have at least one run, even lines consisting of only a newline.

This is a faster alternative to the pango:layout-iter-run function, but the user is not expected to modify the contents of the run (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-iter-line (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The pango:layout-line instance with the current line.
Details:
Gets the current line. Use the faster pango:layout-iter-line-readonly function if you do not plan to modify the contents of the line (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-iter-line-readonly (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The pango:layout-line instance with the current line, that should not be modified.
Details:
Gets the current line for read-only access. This is a faster alternative to the pango:layout-iter-line function, but the user is not expected to modify the contents of the line (glyphs, glyph widths, and so on).
See also:
2025-2-15
Function pango:layout-iter-layout (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
The pango:layout object with the Pango layout associated with iter.
Details:
Gets the Pango layout associated with a Pango layout iterator.
See also:
2025-2-15
Function pango:layout-iter-char-extents (iter extents)
Arguments:
iter -- a pango:layout-iter instance
extents -- a pango:rectangle instance to fill with the logical extents
Details:
Gets the logical extents of the current character, in Pango layout coordinates. Origin is the top left of the entire Pango layout. Only logical extents can sensibly be obtained for characters. Ink extents make sense only down to the level of clusters.
See also:
2025-2-15
Function pango:layout-iter-cluster-extents (iter ink logical)
Arguments:
iter -- a pango:layout-iter instance
ink -- a pango:rectangle instance to fill with the values of the ink extents, or nil
logical -- a pango:rectangle instance to fill with the values of the ink extents, or nil
Details:
Gets the extents of the current cluster, in Pango layout coordinates, origin is the top left of the entire Pango layout.
See also:
2025-2-15
Function pango:layout-iter-run-extents (iter ink logical)
Arguments:
iter -- a pango:layout-iter instance
ink -- a pango:rectangle instance to fill with the values of the ink extents, or nil
logical -- a pango:rectangle instance to fill with the values of the logical extents, or nil
Details:
Gets the extents of the current run in Pango layout coordinates (origin is the top left of the entire Pango layout).
See also:
2025-2-15
Function pango:layout-iter-line-yrange (iter)
Arguments:
iter -- a pango:layout-iter instance
Returns:
y0 -- an integer with the start of the line
y1 -- an integer with the end of the line
Details:
Divides the vertical space in the Pango layout being iterated over between the lines in the Pango layout, and returns the space belonging to the current line. A line's range includes the line's logical extents, plus half of the spacing above and below the line, if the pango:layout-spacing function has been called to set layout spacing. The y0 and y1 positions are in Pango layout coordinates (origin at top left of the entire layout).
Note:
Since 1.44, Pango uses line heights for placing lines, and there may be gaps between the ranges returned by this function.
See also:
2025-2-15
Function pango:layout-iter-line-extents (iter ink logical)
Arguments:
iter -- a pango:layout-iter instance
ink -- a pango:rectangle instance to fill with the values of the ink extents, or nil
ink -- a pango:rectangle instance to fill with the values of the logical extents, or nil
Details:
Obtains the extents of the current line. Extents are in Pango layout coordinates (origin is the top-left corner of the entire Pango layout). Thus the extents returned by this function will be the same width/height but not at the same x/y as the extents returned from the pango:layout-line-extents function.
See also:
2025-2-15
Function pango:layout-iter-layout-extents (iter ink logical)
Arguments:
iter -- a pango:layout-iter instance
ink -- a pango:rectangle instance to fill with the values of the ink extents, or nil
ink -- a pango:rectangle instance to fill with the values of the logical extents, or nil
Details:
Obtains the extents of the Pango layout being iterated over.
See also:
2025-2-15

Types and functions for PangoLayoutLine

GBoxed pango:layout-line
Declaration:
(gobject:define-gboxed-cstruct layout-line "PangoLayoutLine"
  (:export t
   :type-initializer "pango_layout_line_get_type")
  (layout (g:object layout))
  (start-index :int)
  (length :int)
  (runs (g:slist-t (g:boxed glyph-item)))
  (is-paragraph-start :uint)
  (resolved-dir :uint))  
Values:
layout
The pango:layout object this line belongs to, might be nil.
start-index
The integer with the start of line as byte index into the layout text.
length
The integer with the length of line in bytes.
runs
List of runs in the line, from left to right.
is-paragraph-start
True if this is the first line of the paragraph.
resolved-dir
Resolved pango:direction value of line.
Details:
The pango:layout-line structure represents one of the lines resulting from laying out a paragraph via a pango:layout object. The pango:layout-line instances are obtained by calling the pango:layout-line function and are only valid until the text, attributes, or settings of the parent pango:layout object are modified. Routines for rendering pango:layout objects are provided in code specific to each rendering system.
See also:
2025-2-15
Function pango:layout-line-extents (line ink logical)
Arguments:
line -- a pango:layout-line instance
ink -- a pango:rectangle instance to fill with the values of the ink extents of the glyph string as drawn, or nil
logical -- a pango:rectangle instance to fill with the values of the logical extents of the glyph string as drawn, or nil
Details:
Computes the logical and ink extents of a Pango layout line. See the pango:font-glyph-extents function for details about the interpretation of the rectangles.
See also:
2025-2-15
Function pango:layout-line-height (line)
Arguments:
line -- a pango:layout-line instance
Returns:
The integer with the line height.
Details:
Computes the height of the line, that is, the distance between this and the previous lines baseline.

Since 1.44
See also:
#2025-2-15
Function pango:layout-line-length (line)
Arguments:
line -- a pango:layout-line instance
Returns:
The integer with the length of the line.
Details:
Returns the length of the line, in bytes.

Since 1.50
See also:
#2025-2-15
Function pango:layout-line-pixel-extents (line ink logical)
Arguments:
line -- a pango:layout-line instance
ink -- a pango:rectangle instance to fill with the values of the ink extents of the glyph string as drawn, or nil
logical -- a pango:rectangle instance to fill with the values of the logical extents of the glyph string as drawn, or nil
Details:
Computes the logical and ink extents of line in device units. This function just calls the pango:layout-line-extents function followed by two pango:extents-to-pixels function calls, rounding ink and logical such that the rounded rectangles fully contain the unrounded one, that is, passes them as first argument to the pango:extents-to-pixels function.
See also:
2025-2-15
Function pango:layout-line-resolved-direction (line)
Arguments:
line -- a pango:layout-line instance
Returns:
The pango:direction value with the resolved direction of the line.
Details:
Returns the resolved direction of the line.

Since 1.50
See also:
#2025-2-15
Function pango:layout-line-start-index (line)
Arguments:
line -- a pango:layout-line instance
Returns:
The integer with the start index of the line.
Details:
Returns the start index of the line, as byte index into the text of the layout.

Since 1.50
See also:
#2025-2-15
Function pango:layout-line-x-ranges (line start end ranges n-ranges)
Arguments:
line -- a pango:layout-line instance
start -- an integer for the start byte index of the logical range. If this value is less than the start index for the line, then the first range will extend all the way to the leading edge of the Pango layout. Otherwise it will start at the leading edge of the first character.
end -- an integer for the ending byte index of the logical range. If this value is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the Pango layout. Otherwise, it will end at the trailing edge of the last character.
ranges -- a pointer to an array of ranges. The array will be of length 2*n_ranges, with each range starting at (*ranges)[2*n] and of width (*ranges)[2*n + 1] - (*ranges)[2*n]. This array must be freed with the glib:free function. The coordinates are relative to the Pango layout and are in Pango units
n-ranges -- a pointer to an integer for the number of ranges stored in ranges.
Details:
Gets a list of visual ranges corresponding to a given logical range. This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire layout, not with respect to the line.
See also:
#2025-2-15
Function pango:layout-line-index-to-x (line index trailing)
Arguments:
line -- a pango:layout-line instance
index -- an integer for the byte offset of a grapheme within the Pango layout
trailing -- a boolean indicating the edge of the grapheme to retrieve the position of, if true, the trailing edge of the grapheme, if false, the leading of the grapheme
Returns:
The integer with the x offset (in Pango units).
Details:
Converts an index within a line to a x position.
See also:
#2025-2-15
Function pango:layout-line-is-paragraph-start (line)
Arguments:
line -- a pango:layout-line instance
Returns:
True if this is the first line.
Details:
Returns whether this is the first line of the paragraph.

Since 1.50
See also:
#2025-2-15
Function pango:layout-line-x-to-index (line xpos)
Syntax:
(pango:layout-line-x-to-index line xpos) => index, trailing, bool
Arguments:
line -- a pango:layout-line instance
xpos -- an integer for the x offset (in Pango units) from the left edge of the line
index -- an integer with the calculated byte index for the grapheme in which the user clicked
trailing -- an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the leading edge of the grapheme.
bool -- false if xpos was outside the line, true if inside
Details:
Converts from x offset to the byte index of the corresponding character within the text of the Pango layout. If xpos is outside the line, index and trailing will point to the very first or very last position in the line. This determination is based on the resolved direction of the paragraph; for example, if the resolved direction is right-to-left, then an x position to the right of the line (after it) results in 0 being stored in index and trailing. An x position to the left of the line results in index pointing to the (logical) last grapheme in the line and trailing being set to the number of characters in that grapheme. The reverse is true for a left-to-right line.
See also:
#2025-2-15

Scripts and Languages

GEnum pango:script
Declaration:
(gobject:define-genum "PangoScript" script
  (:export t
   :type-initializer "pango_script_get_type")
  (:INVALID-CODE -1)
  (:COMMON 0)
  (:INHERITED 1)
  (:ARABIC 2)
  (:ARMENIAN 3)
  (:BENGALI 4)
  (:BOPOMOFO 5)
  (:CHEROKEE 6)
  (:COPTIC 7)
  (:CYRILLIC 8)
  (:DESERET 9)
  (:DEVANAGARI 10)
  (:ETHIOPIC 11)
  (:GEORGIAN 12)
  (:GOTHIC 13)
  (:GREEK 14)
  (:GUJARATI 15)
  (:GURMUKHI 16)
  (:HAN 17)
  (:HANGUL 18)
  (:HEBREW 19)
  (:HIRAGANA 20)
  (:KANNADA 21)
  (:KATAKANA 22)
  (:KHMER 23)
  (:LAO 24)
  (:LATIN 25)
  (:MALAYALAM 26)
  (:MONGOLIAN 27)
  (:MYANMAR 28)
  (:OGHAM 29)
  (:OLD-ITALIC 30)
  (:ORIYA 31)
  (:RUNIC 32)
  (:SINHALA 33)
  (:SYRIAC 34)
  (:TAMIL 35)
  (:TELUGU 36)
  (:THAANA 37)
  (:THAI 38)
  (:TIBETAN 39)
  (:CANADIAN-ABORIGINAL 40)
  (:YI 41)
  (:TAGALOG 42)
  (:HANUNOO 43)
  (:BUHID 44)
  (:TAGBANWA 45)
  (:BRAILLE 46)
  (:CYPRIOT 47)
  (:LIMBU 48)
  (:OSMANYA 49)
  (:SHAVIAN 50)
  (:LINEAR-B 51)
  (:TAI-LE 52)
  (:UGARITIC 53)
  (:NEW-TAI-LUE 54)
  (:BUGINESE 55)
  (:GLAGOLITIC 56)
  (:TIFINAGH 57)
  (:SYLOTI-NAGRI 58)
  (:OLD-PERSIAN 59)
  (:KHAROSHTHI 60)
  (:UNKNOWN 61)
  (:BALINESE 62)
  (:CUNEIFORM 63)
  (:PHOENICIAN 64)
  (:PHAGS-PA 65)
  (:NKO 66)
  (:KAYAH-LI 67)
  (:LEPCHA 68)
  (:REJANG 69)
  (:SUNDANESE 70)
  (:SAURASHTRA 71)
  (:CHAM 72)
  (:OL-CHIKI 73)
  (:VAI 74)
  (:CARIAN 75)
  (:LYCIAN 76)
  (:LYDIAN 77)
  (:BATAK 78)
  (:BRAHMI 79)
  (:MANDAIC 80)
  (:CHAKMA 81)
  (:MEROITIC-CURSIVE 82)
  (:MEROITIC-HIEROGLYPHS 83)
  (:MIAO 84)
  (:SHARADA 85)
  (:SORA-SOMPENG 86)
  (:TAKRI 87)
  (:BASSA-VAH 88)
  (:CAUCASIAN-ALBANIAN 89)
  (:DUPLOYAN 90)
  (:ELBASAN 91)
  (:GRANTHA 92)
  (:KHOJKI 93)
  (:KHUDAWADI 94)
  (:LINEAR-A 95)
  (:MAHAJANI 96)
  (:MANICHAEAN 97)
  (:MENDE-KIKAKUI 98)
  (:MODI 99)
  (:MRO 100)
  (:NABATAEAN 101)
  (:OLD-NORTH-ARABIAN 102)
  (:OLD-PERMIC 103)
  (:PAHAWH-HMONG 104)
  (:PALMYRENE 105)
  (:PAU-CIN-HAU 106)
  (:PSALTER-PAHLAVI 107)
  (:SIDDHAM 108)
  (:TIRHUTA 109)
  (:WARANG-CITI 110)
  (:AHOM 111)
  (:ANATOLIAN-HIEROGLYPHS 112)
  (:HATRAN 113)
  (:MULTANI 114)
  (:OLD-HUNGARIAN 115)
  (:SIGNWRITING 116))  
Details:
The pango:script enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. See Unicode Standard Annex 24.

Note that this enumeration is deprecated and will not be updated to include values in newer versions of the Unicode standard. Applications should use the GUnicodeScript enumeration instead, whose values are interchangeable with the pango:script enumeration.
2025-2-15
GBoxed pango:language
Declaration:
(glib:define-gboxed-opaque language "PangoLanguage"
  :export t
  :type-initializer "pango_language_get_type"
  :alloc (error "PangoLanguage cannot be created from the Lisp side."))  
Returned by:
Details:
The pango:language structure is used to represent a language. It is opaque, and has no user visible fields.
See also:
2025-2-15
Function pango:language-from-string (language)
Arguments:
language -- a string representing a language tag
Returns:
The newly created pango:language instance.
Details:
Takes a RFC-3066 format language tag as a string and convert it to a pango:language instance that can be efficiently copied and compared with other language tags. This function first canonicalizes the string by converting it to lowercase, mapping _ to -, and stripping all characters other than letters and -.

Use the pango:language-default function if you want to get the pango:language instance for the current locale of the process.
Examples:
(pango:language-from-string "de-de") => #<PANGO-LANGUAGE {1006D76393}>
(pango:language-to-string *) => "de-de"    
See also:
2025-2-15
Function pango:language-to-string (language)
Arguments:
language -- a pango:language instance
Returns:
The string representing the Pango language tag.
Details:
Gets the RFC-3066 format string representing the given Pango language tag.
See also:
2025-2-15
Function pango:language-matches (language range)
Arguments:
language -- a pango:language instance
range -- a list of language ranges, separated by ; : , or space characters, each element must either be * or a RFC 3066 language range canonicalized as by the pango:language-from-string function
Returns:
True if a match was found.
Details:
Checks if a language tag matches one of the elements in a list of language ranges. A language tag is considered to match a range in the list if the range is *, the range is exactly the tag, or the range is a prefix of the tag, and the character after it in the tag is -.
Examples:
(pango:language-matches (pango:language-default) "de-de en-gb") => T
(pango:language-matches (pango:language-default) "en-gb") => NIL    
See also:
2025-2-15
Function pango:language-includes-script (language script)
Arguments:
language -- a pango:language instance
script -- a pango:script value
Returns:
True if script is one of the scripts used to write language or nil, if nothing is known about language, including the case that language is nil.
Details:
Determines if script is one of the scripts used to write language. The returned value is conservative. If nothing is known about the language tag language, true will be returned, since, as far as Pango knows, script might be used to write language.

This routine is used in the itemization process of Pango when determining if a supplied language tag is relevant to a particular section of text. It probably is not useful for applications in most circumstances.

This function uses the pango:language-scripts function internally.
See also:
2025-2-15
Function pango:language-scripts (language)
Arguments:
language -- a pango:language instance
Returns:
The list with pango:script values, or nil if Pango does not have any information about this particular language tag, also the case if language is nil.
Details:
Determines the scripts used to to write language. If nothing is known about the language tag language, or if language is nil, then nil is returned. The list of scripts returned starts with the script that the language uses most and continues to the one it uses least.

Most languages use only one script for writing, but there are some that use two (Latin and Cyrillic for example), and a few use three, Japanese for example. Applications should not make any assumptions on the maximum number of scripts returned though, except that it is positive if the return value is not nil, and it is a small number.
See also:
2025-2-15
Function pango:language-default ()
Returns:
The default language as a pango:language instance.
Details:
Returns the pango:language instance for the current locale of the process. Note that this can change over the life of an application.

On Unix systems, this is the return value derived from setlocale(LC_CTYPE, NULL), and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.

On Windows, the C library does not use any such environment variables, and setting them will not affect the behavior of functions like ctime(). The user sets the locale through the Regional Options in the Control Panel. The C library, in the setlocale() function, does not use country and language codes, but country and language names spelled out in English. However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread's current locale.

Your application should call setlocale(LC_ALL, ""); for the user settings to take effect. GTK does this in its initialization functions automatically by calling gtk_set_locale().
Example:
(pango:language-default) => #<PANGO-LANGUAGE {10019E6973}>
(pango:language-to-string *) => "de-de"    
See also:
2025-2-15
Function pango:language-preferred ()
Returns:
The list of pango:language instances, or nil.
Details:
Returns the list of languages that the user prefers, as specified by the PANGO_LANGUAGE or LANGUAGE environment variables, in order of preference. Note that this list does not necessarily include the language returned by the pango:language-default function.

When choosing language specific resources, such as the sample text returned by the pango:language-sample-string function, you should first try the default language, followed by the languages returned by this function.
See also:
2025-2-15
Function pango:language-sample-string (language)
Arguments:
language -- a pango:language instance, or nil
Returns:
The sample string.
Details:
Get a string that is representative of the characters needed to render a particular language. The sample text may be a pangram, but is not necessarily. It is chosen to be demonstrative of normal text in the language, as well as exposing font feature requirements unique to the language. It is suitable for use as sample text in a font selection dialog.

If language is nil, the default language as found by the pango:language-default function is used.

If Pango does not have a sample string for language, the classic "The quick brown fox ..." is returned.
Example:
(pango:language-sample-string (pango:language-default))
=> "Zwölf Boxkämpfer jagen Viktor quer über den großen Sylter Deich."    
See also:
2025-2-15
Function pango:script-sample-language (script)
Arguments:
script -- a pango:script value
Returns:
The pango:language instance that is representative of the script, or nil if no such language exists.
Details:
Given a script, finds a language tag that is reasonably representative of that script. This will usually be the most widely spoken or used language written in that script: for instance, the sample language for the :cyrillic value is ru (Russian), the sample language for the :arabic value is ar.

For some scripts, no sample language will be returned because there is no language that is sufficiently representative. The best example of this is the :han value, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well.

This function checks the environment variables PANGO_LANGUAGE and LANGUAGE, checked in that order, first. If one of them is set, it is parsed as a list of language tags separated by colons or other separators. This function will return the first language in the parsed list that Pango believes may use script for writing. This last predicate is tested using the pango:language-includes-script function. This can be used to control Pango's font selection for non-primary languages. For example, a PANGO_LANGUAGE enviroment variable set to "en:fa" makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found in an otherwise non-Arabic text. The same trick can be used to choose a default language for PANGO_SCRIPT_HAN when setting context language is not feasible.
See also:
2025-2-15

Bidirectional Text

Types and functions to help with handling bidirectional text.

Pango supports bidirectional text (like Arabic and Hebrew) automatically. Some applications however, need some help to correctly handle bidirectional text.

The pango:direction enumeration can be used with the pango:context-base-dir function to instruct Pango about direction of text, though in most cases Pango detects that correctly and automatically. The rest of the facilities in this section are used internally by Pango already, and are provided to help applications that need more direct control over bidirectional setting of text.
GEnum pango:direction
Declaration:
(gobject:define-genum "PangoDirection" direction
  (:export t
   :type-initializer "pango_direction_get_type")
  (:ltr 0)
  (:rtl 1)
  (:ttb-ltr 2)
  (:ttb-rtl 3)
  (:weak-ltr 4)
  (:weak-rtl 5)
  (:neutral 6))  
Values:
:ltr
A strong left-to-right direction.
:rtl
A strong right-to-left direction.
:ttb-ltr
Deprecated value; treated the same as :rtl.
:ttb-rtl
Deprecated value; treated the same as :ltr.
:weak-ltr
A weak left-to-right direction.
:wek-rtl
A weak right-to-left direction.
:neutral
No direction specified.
Details:
The pango:direction enumeration represents a direction in the Unicode bidirectional algorithm. Not every value in this enumeration makes sense for every usage. For example, the return value of the pango:unichar-direction and pango:find-base-dir functions cannot be :weak-ltr or :weak-rtl, since every character is either neutral or has a strong direction. On the other hand the :neutral value does not make sense to pass to the pango:itemize-with-base-dir function.

The :ttb-ltr, :ttb-rtl values come from an earlier interpretation of this enumeration as the writing direction of a block of text and are no longer used. See the pango:gravity enumeration for how vertical text is handled in Pango.
See also:
2024-2-25
Function pango:unichar-direction (ch)
Arguments:
ch -- a Lisp character
Returns:
The pango:direction value with the direction of the characer.
Details:
Determines the inherent direction of a character. Either :ltr, :rtl, or :neutral. This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else.
See also:
2024-2-25
Function pango:find-base-dir (text)
Arguments:
text -- a string with text to process
Returns:
The pango:direction value with the direction corresponding to the first strong character. If no such character is found, then the :neutral value is returned.
Details:
Searches a string for the first character that has a strong direction, according to the Unicode bidirectional algorithm.
See also:
2024-2-25

Vertical Text

Laying text out in vertical directions.
GEnum pango:gravity
Declaration:
(gobject:define-genum "PangoGravity" gravity
  (:export t
   :type-initializer "pango_gravity_get_type")
  (:south 0)
  (:east 1)
  (:north 2)
  (:west 3)
  (:auto 4))  
Values:
:south
Glyphs stand upright (default).
:east
Glyphs are rotated 90 degrees clockwise.
:north
Glyphs are upside-down.
:west
Glyphs are rotated 90 degrees counter-clockwise.
:auto
Gravity is resolved from the context matrix.
Details:
The pango:gravity enumeration represents the orientation of glyphs in a segment of text. This is useful when rendering vertical text layouts. In those situations, the layout is rotated using a non-identity pango:matrix instance, and then glyph orientation is controlled using a pango:gravity value. Not every value in this enumeration makes sense for every usage. For example, the :auto value only can be passed to and returned by the pango:context-base-gravity function.
See also:
2024-2-22
GEnum pango:gravity-hint
Declaration:
(gobject:define-genum "PangoGravityHint" gravity-hint
  (:export t
   :type-initializer "pango_gravity_hint_get_type")
  (:natural 0)
  (:strong 1)
  (:line 2))  
Values:
:natural
Scripts will take their natural gravity based on the base gravity and the script. This is the default.
:strong
Always use the base gravity set, regardless of the script.
:line
For scripts not in their natural direction, e.g. Latin in East gravity, choose per-script gravity such that every script respects the line progression. This means, Latin and Arabic will take opposite gravities and both flow top-to-bottom for example.
Details:
The pango:gravity-hint enumeration defines how horizontal scripts should behave in a vertical context. That is, English excerpt in a vertical paragraph for example.
See also:
2024-2-22
Function pango:gravity-for-matrix (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The gravity of matrix, which will never be :auto, or :south if matrix is nil.
Details:
Finds the gravity that best matches the rotation component in a pango:matrix instance.
See also:
2024-2-22
Function pango:gravity-for-script (script gravity hint)
Arguments:
script -- a pango:script value to query
gravity -- a base pango:gravity value of the paragraph
hint -- a pango:gravity-hint value with the orientation hint
Returns:
Resolved pango:gravity value suitable to use for a run of text with script.
Details:
Based on the script, base gravity, and hint, returns actual gravity to use in laying out a single pango:item instance. If the gravity argument is :auto, it is first replaced with the preferred gravity of script. To get the preferred gravity of a script, pass the :auto and :strong values in.
See also:
2024-2-22
Function pango:gravity-for-script-and-width (script wide gravity hint)
Arguments:
script -- a pango:script value to query
wide -- true for wide characters as returned by g_unichar_iswide()
gravity -- a base pango:gravity value of the paragraph
hint -- a pango:gravity-hint value with the orientation hint
Returns:
Resolved pango:gravity value suitable to use for a run of text with script and wide.
Details:
Based on the script, East Asian width, base gravity, and hint, returns actual gravity to use in laying out a single character or a pango:item instance.

This function is similar to the pango:gravity-for-script function except that this function makes a distinction between narrow/half-width and wide/full-width characters also. Wide/full-width characters always stand upright, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context.

If the gravity argument is :auto, it is first replaced with the preferred gravity of script.
See also:
2024-2-22
Function pango:gravity-to-rotation (gravity)
Arguments:
script -- a pango:script value to query
Returns:
The double float with the rotation value corresponding to gravity.
Details:
Converts a pango:gravity value to its natural rotation in radians. The gravity argument should not be the :auto value. Note that the pango:matrix-rotate function takes angle in degrees, not radians. So, to call the pango:matrix-rotate function with the output of this function you should multiply it by (180 / pi).
See also:
2024-2-22

Rendering with Pango

Introduction to Cairo Rendering

The Cairo library is a vector graphics library with a powerful rendering model. It has such features as anti-aliased primitives, alpha-compositing, and gradients. Multiple backends for Cairo are available, to allow rendering to images, to PDF files, and to the screen on X and on other windowing systems. The functions in this section allow using Pango to render to Cairo surfaces.

Using Pango with Cairo is straightforward. A pango:context object created with the pango:font-map-create-context function can be used on any cairo:context-t instance, but needs to be updated to match the current transformation matrix and target surface of the Cairo context using the pango:cairo-update-context function. The convenience pango:cairo-create-layout and pango:cairo-update-layout functions handle the common case where the program does not need to manipulate the properties of the pango:context object.

When you get the metrics of a layout or of a piece of a layout using functions such as the pango:layout-extents function, the reported metrics are in user-space coordinates. If a piece of text is 10 units long, and you call (cairo:scale cr 2.0), it still is more-or-less 10 units long. However, the results will be affected by hinting (that is, the process of adjusting the text to look good on the pixel grid), so you should not assume they are completely independent of the current transformation matrix. Note that the basic metrics functions in Pango report results in integer Pango units. To get to the floating point units used in Cairo divide by the pango:+scale+ value.
Examples:
Using Pango with Cairo
(defun draw-cairo-rendering (cr width height)
  (let ((radius (- (/ (min width height) 2) 20))
        (circle 260)
        (n-words 12)
        (font "Sans Bold 16"))
    ;; Set up a transformation matrix so that the user space
    ;; coordinates for where we are drawing are [-RADIUS, RADIUS],
    ;; [-RADIUS, RADIUS] We first center, then change the scale
    (cairo:translate cr (+ radius (/ (- width (* 2 radius)) 2))
                        (+ radius (/ (- height (* 2 radius)) 2)))
    (cairo:scale cr (/ radius circle) (/ radius circle))
    ;; Clear surface
    (cairo:set-source-rgb cr 1.0 1.0 1.0)
    (cairo:paint cr)
    ;; Create a PangoLayout, set the font and text
    (let ((layout (pango:cairo-create-layout cr))
          (desc (pango:font-description-from-string font)))
      (setf (pango:layout-text layout) "Crategus")
      (setf (pango:layout-font-description layout) desc)
      ;; Draw the layout n-words times in a circle
      (do* ((i 0 (+ i 1))
            (angle 0 (/ (* 360 i) n-words))
            ;; Gradient color
            (color (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)
                   (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)))
           ((>= i n-words))
           (cairo:save cr)
           (cairo:set-source-rgb cr (/ #xFF 255) (/ #x99 255) color)
           (cairo:rotate cr (/ (* angle pi) 180))
           ;; Inform Pango to re-layout the text with the new
           ;; transformation matrix
           (pango:cairo-update-layout cr layout)
           (multiple-value-bind (width height)
               (pango:layout-size layout)
             (declare (ignore height))
             (cairo:move-to cr (- (/ width 2 pango:+scale+)) (- circle)))
             (pango:cairo-show-layout cr layout)
             (cairo:restore cr)))))        

Types and functions for Cairo rendering

Interface pango:cairo-font
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The pango:cairo-font interface is an interface exported by fonts for use with Cairo. The actual type of the font will depend on the particular font technology Cairo was compiled to use.
See also:
2025-1-1
Interface pango:cairo-font-map
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The pango:cairo-font-map interface is an interface exported by font maps for use with Cairo. The actual type of the font map will depend on the particular font technology Cairo was compiled to use.
See also:
2025-1-1
Function pango:cairo-font-map-default ()
Syntax:
(pango:cairo-font-map-default) => fontmap
(setf (pango:cairo-font-map-default) fontmap)
Arguments:
fontmap -- a pango:font-map object, or nil
Details:
The pango:cairo-font-map-default function gets a default PangoCairo font map to use with Cairo. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use. You generally should only use the pango:font-map and pango:cairo-font-map interfaces on the returned object.

The (setf pango:cairo-font-map-default) function sets a default PangoCairo font map to use with Cairo. This can be used to change the Cairo font backend that the default font map uses. The old default font map is unreffed and the new font map referenced.

Note that the default font map is per-thread. This function only changes the default fontmap for the current thread. Default fontmaps of exisiting threads are not changed. Default fontmaps of any new threads will still be created using the pango:cairo-font-map-new function.

A nil value for fontmap will cause the current default font map to be released and a new default font map to be created on demand, using the pango:cairo-font-map-new function.
See also:
2025-1-1
Function pango:cairo-font-map-new ()
Returns:
The newly allocated pango:font-map object.
Details:
Creates a new PangoCairo font map object. A font map is used to cache information about available fonts, and holds certain global parameters such as the resolution. In most cases, you can use the pango:cairo-font-map-default function instead.

Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use. You generally should only use the pango:font-map and pango:cairo-font-map interfaces on the returned object.
See also:
2025-1-1
Function pango:cairo-font-map-new-for-font-type (fonttype)
Arguments:
fonttype -- a cairo:font-type-t value with the desired font type
Returns:
The newly allocated pango:font-map object of suitable type, or nil if the requested Cairo font backend is not supported or compiled in.
Details:
Creates a new pango:font-map object of the type suitable to be used with the Cairo font backend of type fonttype.

In most cases one should simply use the pango:cairo-font-map-new function, or in fact in most of those cases, just use the pango:cairo-font-map-default function.
See also:
2025-1-1
Function pango:cairo-font-map-font-type (fontmap)
Arguments:
fontmap -- a pango:font-map object
Returns:
The cairo:font-type-t value with the Cairo font backend type.
Details:
Gets the type of the Cairo font backend that fontmap uses.
Example:
(pango:cairo-font-map-font-type (pango:cairo-font-map-default))
=> :FT    
See also:
2025-1-1
Function pango:cairo-font-map-resolution (fontmap)
Syntax:
(pango:cairo-font-map-resolution fontmap) => dpi
(setf (pango:cairo-font-map-resolution fontmap) dpi)
Arguments:
fontmap -- a pango:cairo-font-map object
dpi -- a number coerced to a double float for the resolution in dots per inch, physical inches are not actually involved, the terminology is conventional
Details:
The pango:cairo-font-map-resolution function gets the resolution for the font map. The (setf pango:cairo-font-map-resolution) function sets the resolution. This is a scale factor between points specified in a pango:font-description instance and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high, that is (10 * 96 / 72 = 13.3).
Examples:
(pango:cairo-font-map-resolution (pango:cairo-font-map-default))
=> 96.0d0    
See also:
2025-1-1
Function pango:cairo-context-resolution (context)
Syntax:
(pango:cairo-context-resolution context) => dpi
(setf (pango:cairo-context-resolution context) dpi)
Arguments:
context -- a pango:context object, from a PangoCairo font map
dpi -- a number coerced to a double float for the resolution in dots per inch, physical inches are not actually involved, the terminology is conventional, a 0 or negative value means to use the resolution from the font map
Details:
The pango:cairo-context-resolution function gets the resolution for the Pango context. The (setf pango:cairo-context-resolution) function sets the resolution. This is a scale factor between points specified in a pango:font-description instance and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high, that is (10 * 96 / 72 = 13.3).
See also:
2025-1-1
Function pango:cairo-context-font-options (context)
Syntax:
(pango:cairo-context-font-options context) => options
(setf (pango:cairo-context-font-options context) options)
Arguments:
context -- a pango:context object, from a PangoCairo font map
options -- a cairo:font-options-t instance, or nil to unset any previously set font options
Details:
The pango:cairo-context-font-options function retrieves any font rendering options. This function does not report options that are derived from the target surface by the pango:cairo-update-context function.

The (setf pango:cairo-context-font-options) function sets the font options used when rendering text with the Pango context. These font options override any font options that the pango:cairo-update-context function derives from the target surface.
See also:
2025-1-1
Function pango:cairo-create-context (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The newly created pango:context object.
Details:
Creates a Pango context set up to match the current transformation and target surface of the Cairo context. This Pango context can then be used to create a Pango layout using the pango:layout-new function.

This function is a convenience function that creates a Pango context using the default font map, then updates it to the Cairo context. If you just need to create a Pango layout for use with the Cairo context and do not need to access the pango:context object directly, you can use the pango:cairo-create-layout function instead.
See also:
2025-1-1
Function pango:cairo-update-context (cr context)
Arguments:
cr -- a cairo:context-t instance
context -- a pango:context object, from a PangoCairo font map
Details:
Updates a Pango context previously created for use with Cairo to match the current transformation and target surface of a Cairo context. If any Pango layouts have been created for the Pango context, it is necessary to call the pango:layout-context-changed function on those layouts.
See also:
2025-1-1
Function pango:cairo-create-layout (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The newly created pango:layout object.
Details:
Creates a Pango layout set up to match the current transformation and target surface of the Cairo context. This Pango layout can then be used for text measurement with functions like the pango:layout-size function or drawing with functions like the pango:cairo-show-layout function. If you change the transformation or target surface for the Cairo context, you need to call the pango:cairo-update-layout function.

This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate pango:context object for each Pango layout. This might matter in an application that was laying out large amounts of text.
See also:
2025-1-1
Function pango:cairo-update-layout (cr layout)
Arguments:
cr -- a cairo:context-t instance
layout -- a pango:layout object
Details:
Updates the pango:context object of a pango:layout object created with the pango:cairo-create-layout function to match the current transformation and target surface of a Cairo context.
See also:
2025-1-1
Function pango:cairo-show-glyph-string (cr font glyphs)
Arguments:
cr -- a cairo:context-t instance
font -- a pango:font object from a PangoCairo font map
glyphs -- a pango:glyph-string instance
Details:
Draws the glyphs in glyphs in the specified Cairo context. The origin of the glyphs, the left edge of the baseline, will be drawn at the current point of the Cairo context.
See also:
2025-1-1
Function pango:cairo-show-glyph-item (cr text item)
Arguments:
cr -- a cairo:context-t instance
text -- a string with the UTF-8 text that item refers to
item -- a pango:glyph-item instance
Details:
Draws the glyphs in item in the specified Cairo context, embedding the text associated with the glyphs in the output if the output format supports it, for example PDF, otherwise it acts similar to the pango:cairo-show-glyph-string function.

The origin of the glyphs, the left edge of the baseline, will be drawn at the current point of the Cairo context.
See also:
2025-1-1
Function pango:cairo-show-layout-line (cr line)
Arguments:
cr -- a cairo:context-t instance
line -- a pango:layout-line instance
Details:
Draws a Pango layout line in the specified Cairo context. The origin of the glyphs, the left edge of the line, will be drawn at the current point of the Cairo context.
See also:
#2025-1-1
Function pango:cairo-show-layout (cr layout)
Arguments:
cr -- a cairo:context-t instance
layout -- a pango:layout object
Details:
Draws a Pango layout in the specified Cairo context. The top-left corner of the pango:layout object will be drawn at the current point of the Cairo context.
See also:
2025-1-1
Function pango:cairo-show-error-underline (cr x y width height)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of one corner of the rectangle
y -- a number for the y coordinate of one corner of the rectangle
width -- a number for the width of the rectangle
height -- a number for the height of the rectangle
Details:
Draw a squiggly line in the specified Cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up and down segments and the resulting rectangle is centered in the original rectangle.
Notes:
All numbers are coerced to a double float before being passed to the foreign C function.
See also:
#2025-1-1
Function pango:cairo-glyph-string-path (cr font glyphs)
Arguments:
cr -- a cairo:context-t instance
font -- a pango:font object from a PangoCairo font map
glyphs -- a pango:glyph-string instance
Details:
Adds the glyphs in glyphs to the current path in the specified Cairo context. The origin of the glyphs, the left edge of the baseline, will be at the current point of the Cairo context.
See also:
#2025-1-1
Function pango:cairo-layout-line-path (cr line)
Arguments:
cr -- a cairo:context-t instance
line -- a pango:layout-line instance
Details:
Adds the text in the pango:layout-line instance to the current path in the specified Cairo context. The origin of the glyphs, the left edge of the line, will be at the current point of the Cairo context.
See also:
#2025-1-1
Function pango:cairo-layout-path (cr layout)
Arguments:
cr -- a cairo:context-t instance
layout -- a pango:layout object
Details:
Adds the text in a Pango layout to the current path in the specified Cairo context. The top-left corner of the Pango layout will be at the current point of the Cairo context.
See also:
#2025-1-1
Function pango:cairo-error-underline-path (cr x y width height)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of one corner of the rectangle
y -- a number for the y coordinate of one corner of the rectangle
width -- a number for the width of the rectangle
height -- a number for the height of the rectangle
Details:
Add a squiggly line to the current path in the specified Cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up and down segments and the resulting rectangle is centered in the original rectangle.
Notes:
All numbers are coerced to a double float before being passed to the foreign C function.
See also:
#2025-1-1

Low Level Functionality

Contexts

Global context object.
Class pango:context
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The pango:context object stores global information influencing the operation of Pango, such as the font map used to look up fonts, and default values such as the default language, default gravity, or default font.
2024-2-23
Function pango:context-new ()
Returns:
The newly allocated pango:context object.
Details:
Creates a new Pango Context initialized to default values. This function is not particularly useful as it should always be followed by a call of the pango:context-font-map function, and the pango:font-map-create-context function does these two steps together and hence users are recommended to use that.

If you are using Pango as part of a higher-level system, that system may have its own way of create a Pango context. For instance, the GTK toolkit has, among others, the gtk:widget-pango-context function. Use those instead.
See also:
2024-2-23
Function pango:context-changed (context)
Arguments:
context -- a pango:context object
Details:
Forces a change in the Pango context, which will cause any pango:layout object using this Pango context to re-layout. This function is only useful when implementing a new backend for Pango, something applications will not do. Backends should call this function if they have attached extra data to the context and such data is changed.
See also:
2024-2-23
Function pango:context-serial (context)
Arguments:
context -- a pango:context object
Returns:
The unsigned integer with the current serial number of context.
Details:
Returns the current serial number of the Pango context. The serial number is initialized to a small number larger than zero when a new Pango context is created and is increased whenever the Pango context is changed using any of the setter functions, or the pango:font-map object it uses to find fonts has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals".

This can be used to automatically detect changes to a pango:context object, and is only useful when implementing objects that need update when their Pango context changes, like their Pango layout.
See also:
2024-2-23
Function pango:context-font-map (context)
Syntax:
(pango:context-font-map context) => fontmap
(setf (pango:context-font-map context) fontmap)
Arguments:
context -- a pango:context object
fontmap -- a pango:font-map object
Details:
The pango:context-font-map function gets the pango:font-map object used to look up fonts for this context. The (setf pango:context-font-map) function sets the font map to be searched when fonts are looked-up in this Pango context. This is only for internal use by Pango backends, a pango:context object obtained via one of the recommended methods should already have a suitable font map.
See also:
2024-2-23
Function pango:context-font-description (context)
Syntax:
(pango:context-font-description context) => desc
(setf (pango:context-font-description context) desc)
Arguments:
context -- a pango:context object
desc -- a pango:font-description instance
Details:
The pango:context-font-description function retrieves the default font description for the Pango context. The (setf pango:context-font-description) function sets the default font description for the Pango context.
See also:
2024-2-23
Function pango:context-language (context)
Syntax:
(pango:context-language context) => language
(setf (pango:context-language context) language)
Arguments:
context -- a pango:context object
language -- a pango:language instance, or nil
Details:
The pango:context-language function retrieves the global language tag for the Pango context. The (setf pango:context-language) function sets the global language. The default language for the locale of the running process can be found using the pango:language-default function.
See also:
2024-2-23
Function pango:context-base-dir (context)
Syntax:
(pango:context-base-dir context) => direction
(setf (pango:context-base-dir context) direction)
Arguments:
context -- a pango:context
direction -- a pango:direction value with the base direction
Details:
The pango:context-base-dir function retrieves the base direction for the Pango context. The (setf pango:context-base-dir) function sets the base direction.

The base direction is used in applying the Unicode bidirectional algorithm. If the direction is :ltr or :rtl, then the value will be used as the paragraph direction in the Unicode bidirectional algorithm. A :weak-ltr value or :weak-rtl value is used only for paragraphs that do not contain any strong characters themselves.
See also:
2024-2-23
Function pango:context-base-gravity (context)
Syntax:
(pango:context-base-gravity context) => gravity
(setf (pango:context-base-gravity context) gravity)
Arguments:
context -- a pango:context object
gravity -- a pango:gravity value with the base gravity
Details:
The pango:context-base-gravity function retrieves the base gravity for the Pango context. The (setf pango:context-base-gravity) function sets the base gravity.

The base gravity is used in laying vertical text out.
See also:
2024-2-23
Function pango:context-gravity (context)
Arguments:
context -- a pango:context object
Returns:
The pango:gravity value with the resolved gravity for the Pango context.
Details:
Retrieves the gravity for the Pango context. This is similar to the pango:context-base-gravity function, except for when the base gravity is :auto for which the pango:gravity-for-matrix function is used to return the gravity from the current Pango context matrix.
See also:
2024-2-23
Function pango:context-gravity-hint (context)
Syntax:
(pango:context-gravity-hint context) => hint
(setf (pango:context-gravity-hint context) hint)
Arguments:
context -- a pango:context object
hint -- a pango:gravity-hint value with the gravity hint
Details:
The pango:context-gravity-hint function retrieves the gravity hint for the Pango context. The (setf pango:context-gravity-hint) function sets the gravity hint.

The gravity hint is used in laying vertical text out, and is only relevant if gravity of the Pango context as returned by the pango:context-gravity function is set to the :east or the :west value.
See also:
#2024-2-23
Function pango:context-matrix (context)
Syntax:
(pango:context-matrix context) => matrix
(setf (pango:context-matrix context) matrix)
Arguments:
context -- a pango:context object
matrix -- a pango:matrix instance, or nil to unset any existing matrix, no matrix set is the same as setting the identity matrix
Details:
The pango:contex-matrix function gets the transformation matrix that will be applied when rendering with this Pango context. The (setf pango:context-matrix) function sets the transformation matrix that will be applied when rendering with this Pango context. Note that reported metrics are in the user space coordinates before the application of the matrix, not device-space coordinates after the application of the matrix. So, they do not scale with the matrix, though they may change slightly for different matrices, depending on how the text is fit to the pixel grid.
See also:
#2024-2-23
Function pango:context-round-glyph-positions (context)
Syntax:
(pango:context-round-glyph-positions context) => setting
(setf (pango:context-round-glyph-positions context) setting)
Arguments:
context -- a pango:context object
setting -- a boolean whether to round glyph positions
Details:
The pango:context-round-glyph-positions function returns whether font rendering with this Pango context should round glyph positions and widths. The (setf pango:context-round-glyph-positions) function sets whether font rendering with this Pango context should round glyph positions and widths to integral positions, in device units.

This is useful when the renderer cannot handle subpixel positioning of glyphs. The default value is to round glyph positions, to remain compatible with previous Pango behavior.

Since 1.44
See also:
#2024-2-23
Function pango:context-load-font (context desc)
Arguments:
context -- a pango:context object
desc -- a pango:font-description instance describing the font to load
Returns:
The newly allocated pango:font object that was loaded, or nil if no font matched.
Details:
Loads the font in one of the font maps in the Pango context that is the closest match for desc.
Example:
Get the font for a Pango context.
(let* ((fontmap (pango:cairo-font-map-default))
       (context (pango:font-map-create-context fontmap))
       (desc (pango:font-description-from-string "Sans"))
       (font (pango:context-load-font context desc)))
  font)
=> #<PANGO:FONT {1002920D73}>    
See also:
2024-2-23
Function pango:context-load-fontset (context desc language)
Arguments:
context -- a pango:context object
desc -- a pango:font-description instance describing the fonts to load
language -- a pango:language instance with the fonts will be used for
Returns:
The newly allocated pango:fontset object loaded, or nil if no font matched.
Details:
Load a set of fonts in the Pango context that can be used to render a font matching desc.
:
Get the fontset for a Pango context.
(let* ((fontmap (pango:cairo-font-map-default))
       (context (pango:font-map-create-context fontmap))
       (desc (pango:font-description-from-string "Sans"))
       (lang (pango:language-default))
       (fontset (pango:context-load-fontset context desc lang)))
  fontset)
=> #<PANGO:FONTSET {10040CFD33}>    
See also:
2024-2-23
Function pango:context-metrics (context desc language)
Arguments:
context -- a pango:context object
desc -- a pango:font-description instance, nil means that the font description from the context will be used
language -- a pango:language instance with the language tag of used to determine which script to get the metrics for, nil means that the language tag from the context will be used, if no language tag is set on the Pango context, metrics for the default language, as determined by the pango:language-default function, will be returned
Returns:
The pango:font-metrics instance.
Details:
Get overall metric information for a particular font description. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.

The pango:font-description instance is interpreted in the same way as by the pango:itemize function, and the family name may be a comma separated list of figures. If characters from multiple of these families would be used to render the string, then the returned fonts would be a composite of the metrics for the fonts loaded for the individual families.
See also:
2024-2-23
Function pango:context-list-families (context)
Arguments:
context -- a pango:context object
Returns:
The list of pango:font-family objects.
Details:
List all families for a Pango context.
See also:
2024-2-23

Tab Stops

Structures for storing tab stops. Functions in this section are used to deal with pango:tab-array instances that can be used to set tab stop positions in a pango:layout object.
GEnum pango:tab-align
Declaration:
(gobject:define-genum "PangoTabAlign" tab-align
  (:export t
   :type-initializer "pango_tab_align_get_type")
  (:left 0)
  (:right 1)
  (:center 2)
  (:decimal 3))  
Values:
:left
The text appears to the right of the tab stop position.
:right
The text appears to the left of the tab stop position until the available space is filled. Since 1.50
:center
The text is centered at the tab stop position until the available space is filled. Since 1.50
:decimal
Text before the first occurrence of the decimal point character appears to the left of the tab stop position, until the available space is filled, the rest to the right. Since 1.50
Details:
The pango:tab-align enumeration specifies where the text appears relative to the tab stop position.
See also:
2024-2-24
GBoxed pango:tab-array
Declaration:
(glib:define-gboxed-opaque tab-array "PangoTabArray"
  :export t
  :type-initializer "pango_tab_array_get_type"
  :alloc (%tab-array-new 0 nil))  
Returned by:
Details:
The pango:tab-array structure contains an array of tab stops. The pango:tab-array structure is opaque, and has no user visible fields. It can be used to set tab stops in a pango:layout object. Each tab stop has an alignment, a position, and optionally a character to use as decimal point.
See also:
2024-2-24
Function pango:tab-array-new (size positions-in-pixel)
Arguments:
size -- an integer for the initial number of tab stops to allocate, can be 0
positions-in-pixels -- a boolean whether positions are in pixel units
Returns:
The newly allocated pango:tab-array instance.
Details:
Creates an array of size tab stops. Tab stops are specified in pixel units if positions-in-pixels is true, otherwise in Pango units. All stops are initially at position 0.
See also:
2024-2-24
Function pango:tab-array-new-with-positions (size positions-in-pixel &rest args)
Arguments:
size -- an integer for the initial number of tab stops to allocate, can be 0
positions-in-pixels -- a boolean whether positions are in pixel units
args -- a list of pairs with the pango:tab-align value and position of the tab stops
Returns:
The newly allocated pango:tab-array instance.
Details:
This is a convenience function that creates a pango:tab-array instance and allows you to specify the alignment and position of each tab stop. You must provide an alignment and position for size tab stops.
See also:
2024-2-24
Function pango:tab-array-copy (tabs)
Arguments:
tabs -- a pango:tab-array instance to copy
Returns:
The newly allocated pango:tab-array instance.
Details:
Copies a tab array.
See also:
2024-2-24
Function pango:tab-array-size (tabs)
Arguments:
tabs -- a pango:tab-array instance
Returns:
The integer with the number of tabs in tabs.
Details:
Gets the number of tab stops in the tab array.
See also:
2024-2-24
Function pango:tab-array-resize (tabs size)
Arguments:
tabs -- a pango:tab-array instance
size -- an integer for the new size of tabs
Details:
Resizes a tab array. You must subsequently initialize any tab stops that were added as a result of growing the tab array.
See also:
2024-2-24
Function pango:tab-array-tab (tabs index)
Syntax:
(pango:tab-array-tab tabs index
(setf (pango:tab-array-tab tabs index) (list align pos))
Arguments:
tabs -- a pango:tab-array instance
index -- an integer for the index of the tab stop
align -- a pango:tab-align value
pos -- an integer for the tab position
Details:
=> align, pos The pango:tab-array-tab function gets the alignment and position of a tab stop. The (setf pango:tab-array-tab) function sets the alignment and postion of a tab stop.
See also:
2024-4-24
Function pango:tab-array-tabs (tabs)
Arguments:
tabs -- a pango:tab-array instance
Returns:
The list of pango:tab-align values and positions for the tab stops in the tab array.
Details:
Returns a list of alignment and positiongs of the tab stops in the tab array.
Example:
(setf tabs (pango:tab-array-from-string "100 decimal:150 right:200"))
=> #<PANGO:TAB-ARRAY {1003CAF943}>
(pango:tab-array-tabs tabs)
=> ((:LEFT 100) (:DECIMAL 150) (:RIGHT 200))    
See also:
2024-2-24
Function pango:tab-array-positions-in-pixels (tabs)
Syntax:
(pango:tab-array-positions-in-pixels tabs) => setting
(setf (pango:tab-array-positions-in-pixels tabs) setting)
Arguments:
tabs -- a pango:tab-array instance
setting -- a boolean whether positions ar in pixels
Details:
The pango:tab-array-positions-in-pixels function returns true if the tab positions are in pixels, false if they are in Pango units. The (setf pango:tab-array-positions-in-pixels) function sets whether positions in the tab array are specified in pixels.
Note:
The (setf pango:tab-array-positions-in-pixels) function is availabe since Pango version 1.50.
See also:
2024-2-24
Function pango:tab-array-decimal-point (tabs index)
Syntax:
(pango:tab-array-decimal-point tabs index) => char
(setf (pango:tab-array-decimal-point tabs index) char)
Arguments:
tabs -- a pango:tab-array instance
index -- an integer for the index of a tab stop
char -- a character for the decimal point to use
Details:
The pango:tab-array-decimal-point function gets the Unicode character to use as decimal point. The (setf pango:tab-array-decimal-point) function sets the Unicode character to use as decimal point.

This is only relevant for tabs with :decimal alignment, which align content at the first occurrence of the decimal point character. The default value of 0 means that Pango will use the decimal point according to the current locale.

Since 1.50
See also:
2024-2-24
Function pango:tab-array-sort (tabs)
Arguments:
tabs -- a pango:tab-array instance
Details:
Utility function to ensure that the tab stops are in increasing order.

Since 1.50
See also:
2024-2-24
Function pango:tab-array-from-string (text)
Arguments:
text -- a string with the tab stops for the tab array
Returns:
The newly allocated pango:tab-array instance.
Details:
Deserializes a pango:tab-array instance from a string. This is the counterpart to the pango:tab-array-to-string function. See that function for details about the format.

Since 1.50
See also:
2024-2-24
Function pango:tab-array-to-string (tabs)
Arguments:
tabs -- a pango:tab-array instance
Returns:
The string with the tab stops of the tab array.
Details:
Serializes a pango:tab-array instance to a string. No guarantees are made about the format of the string, it may change between Pango versions. The intended use of this function is testing and debugging. The format is not meant as a permanent storage format.

Since 1.50
See also:
2024-2-24

Coverage Maps

Unicode character range coverage storage.
GEnum pango:coverage-level
Declaration:
(gobject:define-genum "PangoCoverageLevel" coverage-level
  (:export t
   :type-initializer "pango_coverage_level_get_type")
  (:none 0)
  (:fallback 1)
  (:approximate 2)
  (:exact 3))  
Values:
:none
The character is not representable with the font.
:fallback
The character is represented in a way that may be comprehensible but is not the correct graphical form. For instance, a Hangul character represented as a a sequence of Jamos, or a Latin transliteration of a Cyrillic word.
:approximage
The character is represented as basically the correct graphical form, but with a stylistic variant inappropriate for the current script.
:exact
The character is represented as the correct graphical form.
Details:
Used to indicate how well a font can represent a particular Unicode character point for a particular script. Since 1.44, only the :none and :exact values will be returned.
See also:
2024-2-24
Class pango:coverage
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Returned by:
Details:
The pango:coverage class represents a map from Unicode characters to pango:coverage-level values. It is often necessary in Pango to determine if a particular font can represent a particular character, and also how well it can represent that character. The pango:coverage object is a data structure that is used to represent that information. It is an opaque structure with no public fields.
See also:
2024-2-24
Function pango:coverage-new ()
Returns:
The newly allocated pango:coverage object.
Details:
Creates a new pango:coverage object initialized to the :none value of the pango:coverage-level enumeration.
See also:
2024-2-24
Function pango:coverage-get (coverage index)
Arguments:
coverage -- a pango:coverage object
index -- an integer with the index to check
Returns:
The pango:coverage-level value with the coverage level for the character with index.
Details:
Determine whether a particular index is covered by coverage.
See also:
2024-3-4
Function pango:coverage-set (coverage index level)
Arguments:
coverage -- a pango:coverage object
index -- an integet with the index to modify
level -- a new pango:coverage-level value for index
Details:
Modify a particular index within coverage.
See also:
2024-2-24

PangoRenderer

Rendering driver base class.
GEnum pango:render-part
Declaration:
(gobject:define-genum "PangoRenderPart" pango:render-part
  (:export t
   :type-initializer "pango_render_part_get_type")
  (:foreground 0)
  (:background 1)
  (:underline 2)
  (:strikethrough 3)
  (:overline 4))  
Values:
:foreground
The text itself.
:background
The area behind the text.
:underline
Underlines.
:strikethrough
Strikethrough lines.
:overline
Overlines.
Details:
The pango:render-part enumeration defines different items to render for such purposes as setting colors.
See also:
2024-2-24
Class pango:renderer
Superclasses:
gobject:object, common-lisp:standard-object, common-lisp:t
Documented Subclasses:
None
Direct Slots:
None
Details:
The pango:renderer class is a base class that contains the necessary logic for rendering pango:layout or a pango:layout-line objects. By subclassing the pango:renderer class and overriding operations such as draw_glyphs and draw_rectangle, renderers for particular font backends and destinations can be created.
See also:
2024-2-24

Utilities

PangoRectangle and PangoMatrix

CStruct pango:rectangle
Declaration:
(cffi:defcstruct rectangle
  (x :int)
  (y :int)
  (width :int)
  (height :int))  
Values:
x
The x coordinate of the left side of the rectangle.
y
The y coordinate of the the top side of the rectangle.
width
The width of the rectangle.
height
The height of the rectangle.
Slot Access Functions:
Details:
The pango:rectangle structure represents a rectangle. It is frequently used to represent the logical or ink extents of a single glyph or section of text. See, for example, the pango:font-glyph-extents function.
Notes:
The pango:rectangle structure is implemented as a CFFI structure type. It can be created using the cffi:with-foreign-object macro and the slots can be accessed using the cffi:foreign-slot-value function. For convenience, the pango:with-rectangle and pango:with-rectangles macros create and initialize a pango:rectangle instance for use.
See also:
2025-1-1
Accessor pango:rectangle-x (rect)
Syntax:
(pango:rectangle-x rect) => x
(setf (pango:rectangle-x rect) x)
Arguments:
rect -- a pango:rectangle instance
x -- an integer for the x component of the rectangle
Details:
Accessor of the x slot of the pango:rectangle structure.
See also:
2025-1-1
Accessor pango:rectangle-y (rect)
Syntax:
(pango:rectangle-y rect) => y
(setf (pango:rectangle-y rect) y)
Arguments:
rect -- a pango:rectangle instance
y -- an integer for the y component of the rectangle
Details:
Accessor of the y slot of the pango:rectangle structure.
See also:
2025-1-1
Accessor pango:rectangle-width (rect)
Syntax:
(pango:rectangle-width rect) => width
(setf (pango:rectangle-width rect) width)
Arguments:
rect -- a pango:rectangle instance
width -- an integer for the width of the rectangle
Details:
Accessor of the width slot of the pango:rectangle structure.
See also:
2025-1-1
Accessor pango:rectangle-height (rect)
Syntax:
(pango:rectangle-height rect) => heigth
(setf (pango:rectangle-height rect) height)
Arguments:
rect -- a pango:rectangle instance
height -- an integer for the height of the rectangle
Details:
Accessor of the height slot of the pango:rectangle structure.
See also:
2025-1-1
Macro pango:with-rectangle ((var &rest args) &body body)
Syntax:
(pango:with-rectangle (rect) body) => result
(pango:with-rectangle (rect rect1) body) => result
(pango:with-rectangle (rect x y width height) body) => result
Arguments:
rect -- a pango:rectangle instance to create and initialize
rect1 -- a pango:rectangle instance for initialization
x -- an integer for the x coordinate of the rectangle
y -- an integer for the y coordinate of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Details:
The pango:with-rectangle macro allocates a new pango:rectangle instance, initializes the rectangle with the given values and executes the body that uses the rectangle. After execution of the body the allocated memory for the rectangle is released.

When no argument is given the components of the rectangle are initialized to zero. One argument is another rectangle for initialization. The initialization with four integers initializes the x, y, width, and height slots with the given values.
See also:
2025-1-1
Macro pango:with-rectangles (vars &body body)
Syntax:
(pango:with-rectangles (rect1 ... rectn) body) => result
Arguments:
rect1 ... rectn -- newly created pango:rectangle instances
body -- a body that uses the bindings rect1 ... rectn
Details:
The pango:with-rectangles macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each rectangle can be initialized with values using the syntax for the pango:with-rectangle macro.
See also:
2025-1-1
Function pango:rectangle-to-integer (rect)
Syntax:
(pango:rectangle-to-integer rect) => x, y, width, height
Arguments:
rect -- a pango:rectangle instance
x -- an integer for the x component of the rectangle
y -- an integer for the y component of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Details:
Retrieves the components of rect as integers.
See also:
2025-1-1
GBoxed pango:matrix
Declaration:
(glib:define-gboxed-cstruct matrix "PangoMatrix"
  (:export t
   :type-initializer "pango_matrix_get_type")
  (xx :double :initform 0.0d0)
  (xy :double :initform 0.0d0)
  (yx :double :initform 0.0d0)
  (yy :double :initform 0.0d0)
  (x0 :double :initform 0.0d0)
  (y0 :double :initform 0.0d0))  
Values:
xx
1st component of the transformation matrix.
xy
2nd component of the transformation matrix.
yx
3rd component of the transformation matrix.
yy
4th component of the transformation matrix.
x0
x translation.
y0
y translation.
Returned by:
Slot Access Functions:
Details:
A structure specifying a transformation between user-space coordinates and device coordinates. The transformation is given by
xdevice = xuser * xx + yuser * xy + x0
ydevice = xuser * yx + yuser * yy + y0  
2025-1-3
Accessor pango:matrix-xx (instance)
Syntax:
(pango:matrix-xx instance) => xx
(setf (pango:matrix-xx instance) xx)
Arguments:
instance -- a pango:matrix instance
xx -- a double float for the xx component of the transformation matrix
Details:
Accessor of the xx slot of the pango:matrix structure.
See also:
2025-1-3
Accessor pango:matrix-xy (instance)
Syntax:
(pango:matrix-xy instance) => xy
(setf (pango:matrix-xy instance) xy)
Arguments:
instance -- a pango:matrix instance
xy -- a double float for the xy component of the transformation matrix
Details:
Accessor of the xy slot of the pango:matrix structure.
See also:
2025-1-3
Accessor pango:matrix-yx (instance)
Syntax:
(pango:matrix-yx instance) => yx
(setf (pango:matrix-yx instance) yx)
Arguments:
instance -- a pango:matrix instance
yx -- a double float for the yx component of the transformation matrix
Details:
Accessor of the yx slot of the pango:matrix structure.
See also:
2025-1-3
Accessor pango:matrix-yy (instance)
Syntax:
(pango:matrix-yy instance) => yy
(setf (pango:matrix-yy instance) yy)
Arguments:
instance -- a pango:matrix instance
yy -- a double float for the yy component of the transformation matrix
Details:
Accessor of the yy slot of the pango:matrix structure.
See also:
2025-1-3
Accessor pango:matrix-x0 (instance)
Syntax:
(pango:matrix-x0 instance) => x0
(setf (pango:matrix-x0 instance) x0)
Arguments:
instance -- a pango:matrix instance
x0 -- a double float for the x0 component of the transformation matrix
Details:
Accessor of the x0 slot of the pango:matrix structure.
See also:
2025-1-3
Accessor pango:matrix-y0 (instance)
Syntax:
(pango:matrix-y0 instance) => y0
(setf (pango:matrix-y0 instance) y0)
Arguments:
instance -- a pango:matrix instance
y0 -- a double float for the y0 component of the transformation matrix
Details:
Accessor of the y0 slot of the pango:matrix structure.
See also:
2025-1-3
Function pango:matrix-new (&key xx xy yx yy x0 y0)
Arguments:
xx, xy, yx, yy, x0, y0 -- numbers coerced to double floats for the components of the transformation matrix, the default values are 0.0d0
Returns:
The newly allocated pango:matrix instance.
Details:
Creates a new Pango matrix with the given values.
See also:
2025-1-3
Function pango:matrix-init ()
Returns:
The newly allocated pango:matrix initialized to the identity transformation.
Details:
Returns a Pango matrix initialized to the identity transformation
Example:
(let ((matrix (pango:matrix-init)))
  (pango:matrix-rotate matrix 45.0d0)
  ... )    
See also:
2025-1-3
Function pango:matrix-copy (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The newly allocated pango:matrix instance.
Details:
Copies a Pango matrix.
See also:
2025-1-3
Function pango:matrix-to-float (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The list with the components of matrix as floating point values.
Details:
Converts the matrix to a list with the components.
Notes:
This function is a Lisp extension and not present in the C library.
See also:
2025-1-3
Function pango:matrix-translate (matrix tx ty)
Arguments:
matrix -- a pango:matrix instance
tx -- a number coerced to a double float for the amount to translate in the x direction
ty -- a number coerced to a double float for the amount to translate in the y direction
Returns:
The pango:matrix instance with the transformation.
Details:
Changes the transformation represented by matrix to be the transformation given by first translating by (tx,ty) then applying the original transformation.
See also:
2025-1-3
Function pango:matrix-scale (matrix sx sy)
Arguments:
matrix -- a pango:matrix instance
sx -- a number coerced to a double float for the amount to scale by in x direction
sy -- a number coerced to a double float for the amount to scale by in y direction
Returns:
The pango:matrix instance with the transformation.
Details:
Changes the transformation represented by matrix to be the transformation given by first scaling by sx in the x direction and sy in the y direction then applying the original transformation.
See also:
2025-1-3
Function pango:matrix-rotate (matrix degrees)
Arguments:
matrix -- a pango:matrix instance
degrees -- a number coerced to a double float for the degrees to rotate counter-clockwise
Returns:
The pango:matrix instance with the transformation.
Details:
Changes the transformation represented by matrix to be the transformation given by first rotating by degrees counter-clockwise then applying the original transformation.
See also:
2025-1-3
Function pango:matrix-concat (matrix other)
Arguments:
matrix -- a pango:matrix instance
other -- a pango:matrix instance
Returns:
The pango:matrix instance with the transformation.
Details:
Changes the transformation represented by matrix to be the transformation given by first applying the transformation given by other then applying the original transformation.
See also:
2025-1-3
Function pango:matrix-transform-point (matrix x y)
Arguments:
matrix -- a pango:matrix instance
x -- a number coerced to a double float for the x position
y -- a number coerced to a double float for the y position
Returns:
The double floats for the transformed point (x,y).
Details:
Transforms the point (x,y) by matrix.
See also:
2025-1-3
Function pango:matrix-transform-distance (matrix dx dy)
Arguments:
matrix -- a pango:matrix instance
dx -- a number coerced to a double float for the x component
dy -- a number coerced to a double float for the y component
Returns:
The double floats for the transformed distance vector (dx,dy).
Details:
Transforms the distance vector (dx,dy) by matrix. This is similar to the pango:matrix-transform-point function except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows:
dx2 = dx1 * xx + dy1 * xy;
dy2 = dx1 * yx + dy1 * yy;  
Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1,y1) transforms to (x2,y2) then (x1+dx1, y1+dy1) will transform to (x1+dx2, y1+dy2) for all values of x1 and x2.
See also:
2025-1-3
Function pango:matrix-transform-rectangle (matrix rect)
Arguments:
matrix -- a pango:matrix instance
rect -- a pango:rectangle instance
Returns:
The transformed pango:rectangle instance with the bounding box.
Details:
First transforms rect using matrix, then calculates the bounding box of the transformed rectangle. The rectangle should be in Pango units. This function is useful for example when you want to draw a rotated pango:layout object to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering. If you have a rectangle in device units (pixels), use the pango:matrix-transform-pixel-rectangle function.

If you have the rectangle in Pango units and want to convert to transformed pixel bounding box, it is more accurate to transform it first using this function and pass the result to the pango:extents-to-pixels functions first argument, for an inclusive rounded rectangle. However, there are valid reasons that you may want to convert to pixels first and then transform, for example when the transformed coordinates may overflow in Pango units, large matrix translation for example.
See also:
2025-1-3
Function pango:matrix-transform-pixel-rectangle (matrix rect)
Arguments:
matrix -- a pango:matrix instance
rect -- a pango:rectangle instance
Returns:
The transformed pango:rectangle instance with the bounding box.
Details:
First transforms rect using matrix, then calculates the bounding box of the transformed rectangle. The rectangle should be in device units (pixels). This function is useful for example when you want to draw a rotated pango:layout object to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering.

For better accuracy, you should use the pango:matrix-transform-rectangle function on the original rectangle in Pango units and convert to pixels afterward using the pango:extents-to-pixels functions first argument.
See also:
2025-1-3
Function pango:matrix-font-scale-factor (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The double float with the scale factor of matrix on the height of the font, or 1.0 if matrix is nil.
Details:
Returns the scale factor of a matrix on the height of the font. That is, the scale factor in the direction perpendicular to the vector that the x coordinate is mapped to.
See also:
2025-1-3
Function pango:matrix-font-scale-factors (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The double floats with the xscale scale factor in the x direction and yscale scale factor in the y direction.
Details:
Calculates the scale factors of a matrix on the width and height of the font. That is, xscale is the scale factor in the direction of the x coordinate, and yscale is the scale factor in the direction perpendicular to the vector that the x coordinate is mapped to.

Note that output numbers will always be non-negative.
See also:
2025-1-3
Function pango:matrix-slant-ratio (matrix)
Arguments:
matrix -- a pango:matrix instance
Returns:
The double float with the slant ration of matrix.
Details:
Gets the slant ratio of the matrix. This is λ for a shear matrix in the form
1 λ
0 1  
Since 1.50
See also:
2025-1-3

Utilities

Constant pango:+scale+
Initial Value:
1024
Details:
The pango:+scale+ constant represents the scale between dimensions used for Pango distances and device units. The definition of device units is dependent on the output device. It will typically be pixels for a screen, and points for a printer. The pango:+scale+ value is currently 1024, but this may be changed in the future.

When setting font sizes, device units are always considered to be points as in "12 point font", rather than pixels.
See also:
2024-3-3
Function pango:pixels (d)
Arguments:
d -- a dimension in Pango units
Returns:
Rounded dimension in device units.
Details:
Converts a dimension to device units by rounding.
See also:
2024-3-6
Function pango:ascent (rect)
Arguments:
rect -- a pango:rectangle instance
Details:
Extracts the ascent from a pango:rectangle instance representing glyph extents. The ascent is the distance from the baseline to the highest point of the character. This is positive if the glyph ascends above the baseline.
See also:
2024-3-6
Function pango:descent (rect)
Arguments:
rect -- a pango:rectangle instance
Details:
Extracts the descent from a pango:rectangle instance representing glyph extents. The descent is the distance from the baseline to the lowest point of the character. This is positive if the glyph descends below the baseline.
See also:
2024-3-6
Function pango:lbearing (rect)
Arguments:
rect -- a pango:rectangle instance
Details:
Extracts the left bearing from a pango:rectangle instance representing glyph extents. The left bearing is the distance from the horizontal origin to the farthest left point of the character. This is positive for characters drawn completely to the right of the glyph origin.
See also:
2024-3-6
Function pango:rbearing (rect)
Arguments:
rect -- a pango:rectangle instance
Details:
Extracts the right bearing from a pango:rectangle instance representing glyph extents. The right bearing is the distance from the horizontal origin to the farthest right point of the character. This is positive except for characters drawn completely to the left of the horizontal origin.
See also:
2024-3-6
Function pango:extents-to-pixels (inclusive nearest)
Arguments:
inclusive -- a pango:rectangle instance to round to pixels inclusively, or NULL
nearest -- a pango:rectangle instance to round to nearest pixels, or NULL
Details:
Converts extents from Pango units to device units, dividing by the pango:+scale+ factor and performing rounding.

The inclusive rectangle is converted by flooring the x/y coordinates and extending width/height, such that the final rectangle completely includes the original rectangle.

The nearest rectangle is converted by rounding the coordinates of the rectangle to the nearest device unit (pixel).

The rule to which argument to use is: if you want the resulting device-space rectangle to completely contain the original rectangle, pass it in as inclusive. If you want two touching-but-not-overlapping rectangles stay touching-but-not-overlapping after rounding to device units, pass them in as nearest.
See also:
2023-12-25

PangoColor

GBoxed pango:color
Declaration:
(glib:define-gboxed-cstruct color "PangoColor"
  (:export t
   :type-initializer "pango_color_get_type")
  (red :uint16 :initform 0)
  (green :uint16 :initform 0)
  (blue :uint16 :initform 0))  
Values:
red
The unsigned integer with the red component of the color.
green
The unsigned integer with the green component of the color.
blue
The unsigned integer with the blue component of the color.
Returned by:
Slot Access Functions:
Details:
The pango:color structure is used to represent a color in an uncalibrated RGB color space.
2025-2-15
Accessor pango:color-red (instance)
Syntax:
(pango:color-red instance) => red
(setf (pango:color-red instance) red)
Details:
Accessor of the red slot of the pango:color color. The red component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity.
See also:
2025-2-15
Accessor pango:color-green (instance)
Syntax:
(pango:color-green instance) => green
(setf (pango:color-green instance) green)
Details:
Accessor of the green slot of the pango:color color. The green component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity.
See also:
2025-2-15
Accessor pango:color-blue (instance)
Syntax:
(pango:color-blue instance) => blue
(setf (pango:color-blue instance) blue)
Details:
Accessor of the blue slot of the pango:color color. The blue component of the color. This is a value between 0 and 65535, with 65535 indicating full intensity.
See also:
2025-2-15
Function pango:color-new (&key red green blue)
Arguments:
red -- an unsigned integer for the red component of the color
green -- an unsigned integer for the green component of the color
blue -- an unsigned integer for the blue component of the color
Details:
Creates a new pango:color color. The values are between 0 and 65535, with 65535 indicating full intensity.
See also:
2025-2-15
Function pango:color-copy (color)
Arguments:
color -- a pango:color instance
Returns:
The newly created pango:color instance.
Details:
Creates a copy of color.
See also:
2025-2-15
Function pango:color-parse (spec)
Arguments:
spec -- a string specifying a color
Returns:
The newly created pango:color instance with the result, or nil.
Details:
Fill in the fields of a color from a string specification. The string can either one of a large set of standard names, taken from the X11 rgb.txt file, or it can be a hex value in the form #rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb where r, g, and b are hex digits of the red, green, and blue components of the color, respectively. White in the four forms is #fff, #ffffff, #fffffffff and #ffffffffffff.
Examples:
(pango:color-parse "blue")
=> #S(PANGO:COLOR :RED 0 :GREEN 0 :BLUE 65535)
(pango:color-to-string *)
=> "#00000000ffff"
(pango:color-parse "white")
=> #S(PANGO:COLOR :RED 65535 :GREEN 65535 :BLUE 65535)
(pango:color-to-string *)
=> "#ffffffffffff"    
See also:
2025-2-15
Function pango:color-parse-with-alpha (spec)
Syntax:
(pango:color-parse-with-alpha spec) => color, alpha
Arguments:
spec -- a string specifying a color
color -- a newly created pango:color instance with the result, or nil
alpha -- an unsigned integer for the alpha value
Details:
Fill in the fields of a color from a string specification. The string can either one of a large set of standard names, taken from the CSS specification, or it can be a hexadecimal value in the form #rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb where r, g and b are hex digits of the red, green, and blue components of the color, respectively. White in the four forms is #fff, #ffffff, #fffffffff and #ffffffffffff.

Additionally, parse strings of the form #rgba, #rrggbbaa, #rrrrggggbbbbaaaa, and set alpha to the value specified by the hex digits for a. If no alpha component is found in spec, alpha is set to 0xffff, for a solid color.
See also:
2025-2-15
Function pango:color-to-string (color)
Arguments:
color -- a pango:color instance
Returns:
The string with the hexadecimal form of color.
Details:
Returns a textual specification of color in the hexadecimal form #rrrrggggbbbb, where r, g and b are hex digits representing the red, green, and blue components respectively.
See also:
2025-2-15

Version Information

Tools for checking Pango version at compile and run time.
Function pango:version ()
Returns:
The integer with the encoded version of the Pango library available at run time.
Details:
Returns the encoded version of Pango available at run-time.
Example:
(pango:version) => 15006    
See also:
2024-2-24
Function pango:version-string ()
Returns:
The string containing the version of the Pango library available at run time.
Details:
Returns the version of Pango available at run-time
Example:
(pango:version-string) => "1.50.6"    
See also:
2024-2-24
Function pango:version-check (major minor micro)
Arguments:
major -- an integer for the required major version
minor -- an integer for the required minor version
micro -- an integer for the required major version
Returns:
Returns nil if the Pango library is compatible with the given version, or a string describing the version mismatch.
Details:
Checks that the Pango library in use is compatible with the given version. Compatibility is defined by two things: first the version of the running library is newer than the major.minor.micro version. Second the running library must be binary compatible with the major.minor.micro version (same major version).
Example:
(pango:version-check 1 48 0) => NIL
(pango:version-check 1 52 0) => "Pango version too old (micro mismatch)"    
See also:
2024-2-24



Package cairo

Cairo is a software library used to provide a vector graphics-based, device-independent API for software developers. It is designed to provide primitives for 2-dimensional drawing across a number of different backends. Cairo is designed to use hardware acceleration when available. This is the API documentation of a Lisp binding to Cairo.

Drawing

The Cairo drawing context

The cairo:context-t structure is the main object used when drawing with Cairo. To draw with Cairo, you create a cairo:context-t instance, set the target surface, and drawing options for the cairo:context-t instance, create shapes with functions like the cairo:move-to and cairo:line-to functions, and then draw shapes with the cairo:stroke or cairo:fill functions.

The cairo:context-t instance can be pushed to a stack via the cairo:save function. They may then safely be changed, without losing the current state. Use the cairo:restore function to restore to the saved state.

Types and functions for Cairo drawing

CEnum cairo:antialias-t
Declaration:
(cffi:defcenum antialias-t
  :default
  :none
  :gray
  :subpixel
  :fast
  :good
  :best)  
Values:
:default
Use the default antialiasing for the subsystem and target device.
:none
Use a bilevel alpha mask.
:gray
Perform single-color antialiasing, using shades of gray for black text on a white background, for example.
:subpixel
Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels.
:fast
Hint that the backend should perform some antialiasing but prefer speed over quality.
:good
Hint that the backend should balance quality against performance.
:best
Hint that the backend should render at the highest quality, sacrificing speed if necessary.
Details:
The cairo:antialias-t enumeration 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, there is also a set of hints that have the :fast, :good, and :best values.

These hints 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, the :fast and :good values will be mapped to the :gray value, with the :best value being equivalent to the :subpixel value. The interpretation of the :default value is left entirely up to the backend, typically this will be similar to the :good value.
See also:
2025-1-2
CEnum cairo:fill-rule-t
Declaration:
(cffi:defcenum fill-rule-t
  :winding
  :even-odd)  
Values:
:winding
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.
:even-odd
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.
Details:
The cairo:fill-rule-t enumeration 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 does not 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 the :winding value.
See also:
2025-1-2
CEnum cairo:line-cap-t
Declaration:
(cffi:defcenum line-cap-t
  :butt
  :round
  :square)  
Values:
:butt
Start (stop) the line exactly at the start (end) point.
:round
Use a round ending, the center of the circle is the end point.
:square
Use squared ending, the center of the square is the end point.
Details:
The cairo:line-cap-t enumeration specifies how to render the endpoints of the path when stroking. The default line cap style is the :butt value.
See also:
2025-1-2
CEnum cairo:line-join-t
Declaration:
(cffi:defcenum line-join-t
  :miter
  :round
  :bevel)  
Values:
:miter
Use a sharp (angled) corner, see the cairo:miter-limit function.
:round
Use a rounded join, the center of the circle is the joint point.
:bevel
Use a cut-off join, the join is cut off at half the line width from the joint point.
Details:
The cairo:line-join-t enumeration specifies how to render the junction of two lines when stroking. The default line join style is the :miter value.
See also:
2025-1-2
CEnum cairo:operator-t
Declaration:
(cffi:defcenum operator-t
  :clear
  :source
  :over
  :in
  :out
  :atop
  :dest
  :dest-over
  :dest-in
  :dest-out
  :dest-atop
  :xor
  :add
  :saturate
  :multiply
  :screen
  :overlay
  :darken
  :lighten
  :color-dodge
  :color-burn
  :hard-light
  :soft-ligth
  :difference
  :exclusion
  :hsl-hue
  :hsl-saturation
  :hsl-color
  :hsl-luminosity)  
Values:
:clear
Clear destination layer (bounded).
:source
Replace destination layer (bounded).
:over
Draw source layer on top of destination layer (bounded).
:in
Draw source where there was destination content (unbounded).
:out
Draw source where there was no destination content (unbounded).
:atop
Draw source on top of destination content and only there.
:dest
Ignore the source.
:dest-over
Draw destination on top of source.
:dest-in
Leave destination only where there was source content (unbounded).
:dest-out
Leave destination only where there was no source content.
:dest-atop
Leave destination on top of source content and only there (unbounded).
:xor
Source and destination are shown where there is only one of them.
:add
Source and destination layers are accumulated.
:saturate
Like over, but assuming source and dest are disjoint geometries.
:multiply
Source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs.
:screen
Source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs.
:overlay
Multiplies or screens, depending on the lightness of the destination color.
:darken
Replaces the destination with the source if it is darker, otherwise keeps the source.
:lighten
Replaces the destination with the source if it is lighter, otherwise keeps the source.
:dodge
Brightens the destination color to reflect the source color.
:burn
Darkens the destination color to reflect the source color.
:hard-light
Multiplies or screens, dependent on source color.
:soft-light
Darkens or lightens, dependent on source color.
:difference
Takes the difference of the source and destination color.
:exclusion
Produces an effect similar to difference, but with lower contrast.
:hsl-hue
Creates a color with the hue of the source and the saturation and luminosity of the target.
:hsl-saturation
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.
:hsl-color
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.
:hsl-luinosity
Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to the :hsl-color value.
Details:
The cairo:operator-t enumeration is used to set the compositing operator for all Cairo drawing operations. The default operator is the :over value. 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 Cairo's Compositing Operators.
See also:
2025-1-2
CStruct cairo:context-t
Returned by:
Details:
The cairo:context-t structure contains the current state of the rendering device, including coordinates of yet to be drawn shapes. Cairo contexts, as cairo:context-t instances are named, are central to Cairo and all drawing with Cairo is always done to a cairo:context-t instance.

Use the cairo:create function or the cairo:with-context macro to create a Cairo context for a target surface. Memory management of the cairo:context-t instance is done with the cairo:reference and cairo:destroy functions.
See also:
2025-1-2
Macro cairo:with-context ((context target) &body body)
Syntax:
(cairo:with-context (context surface) body) => result
Arguments:
context -- a newly allocated cairo:context-t instance
target -- a cairo:surface-t instance for the target surface
Details:
The cairo:with-context macro allocates a new cairo:context-t instance for the given target and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo context is released.

This macro allocates the Cairo context with the cairo:create function and destroys it with the cairo:destroy function.
See also:
2025-1-2
Function cairo:create (target)
Arguments:
target -- a cairo:surface-t instance for the target surface for the Cairo context
Returns:
The newly allocated cairo:context-t instance.
Details:
Creates a new Cairo 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 the cairo:image-surface-create function, or any other variant.

The initial reference count should be released with the cairo:destroy function when you are done using the Cairo context. This function will always return a valid Cairo context. If memory cannot be allocated, a special Cairo context will be returned on which the cairo:status function returns the :no-memory value. If you attempt to target a surface which does not support writing, then a :write-error value will be raised. You can use this object normally, but no drawing will be done.

This function references target, so you can immediately call the cairo:surface-destroy function on it if you do not need to maintain a separate reference to it.
See also:
2025-1-2
Function cairo:reference (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The referenced cairo:context-t instance.
Details:
Increases the reference count on the Cairo context by one. This prevents the Cairo context from being destroyed until a matching call to the cairo:destroy function is made. The number of references to a Cairo context can be get using the cairo:reference-count function.
See also:
2025-1-2
Function cairo:reference-count (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The unsigned integer with the current reference count of cr.
Details:
Returns the current reference count of the Cairo context. If the Cairo context is a "nil" context, 0 will be returned.
See also:
2025-1-2
Function cairo:destroy (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Decreases the reference count on the Cairo context by one. If the result is zero, then the Cairo context and all associated resources are freed. See the cairo:reference function.
See also:
2025-1-2
Function cairo:status (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The cairo:status-t value with the current status of cr.
Details:
Checks whether an error has previously occurred for the Cairo context. See the cairo:status-t enumeration.
See also:
2025-1-2
Function cairo:save (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Makes a copy of the current state of cr and saves it on an internal stack of saved states for cr. When the cairo:restore function is called, the Cairo context will be restored to the saved state. Multiple calls to the cairo:save and cairo:restore functions can be nested. Each call to the cairo:restore function restores the state from the matching paired cairo:save call.

It is not necessary to clear all saved states before a Cairo context is freed. If the reference count of a Cairo context drops to zero in response to a call to the cairo:destroy function, any saved states will be freed along with the Cairo context.
See also:
2025-1-2
Function cairo:restore (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Restores cr to the state saved by a preceding call to the cairo:save function and removes that state from the stack of saved states.
See also:
2025-1-2
Function cairo:target (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The cairo:surface-t instance with the target surface. This object is owned by Cairo.
Details:
Gets the target surface for the Cairo context as passed to the cairo:create function. To keep a reference to it, you must call the cairo:surface-reference function.

This function will always return a valid Cairo surface, but the result can be a "nil" surface if cr is already in an error state.
See also:
2025-1-2
Function cairo:push-group (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to the cairo:pop-group or cairo:pop-group-to-source function. 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 the cairo:push-group and cairo:pop-group functions. Each call pushes and pops the new target group onto and from a stack.

The cairo:push-group function calls the cairo:save function so that any changes to the graphics state will not be visible outside the group, the pop group functions call the cairo:restore function.

By default the intermediate group will have a :color-alpha value of the cairo:content-t enumeration. Other content types can be chosen for the group by using the cairo:push-group-with-content function instead.
Examples:
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:
(cairo:push-group cr)
(setf (cairo:source cr) fill-pattern)
(cairo:fill-preserve cr)
(setf (cairo:source cr) stroke-pattern)
(cairo:stroke cr)
(cairo:pop-group-to-source cr)
(cairo:paint-with-alpha cr alpha)    
See also:
#2025-1-2
Function cairo:push-group-with-content (cr content)
Arguments:
cr -- a cairo:context-t instance
content -- a cairo:content-t value indicating the type of group that will be created
Details:
Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to the cairo:pop-group or cairo:pop-group-to-source function. 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.

The ability to control the content type is the only distinction between this function and the cairo:push-group function which you should see for a more detailed description of group rendering.
See also:
#2025-1-2
Function cairo:pop-group (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The newly created cairo:pattern-t instance containing the results of all drawing operations performed to the group. The caller owns the returned instance and should call the cairo:pattern-destroy function when finished with it.
Details:
Terminates the redirection begun by a call to the cairo:push-group or cairo:push-group-with-content function and returns a new pattern containing the results of all drawing operations performed to the group.

The cairo:pop-group function calls the cairo:restore function, balancing a call to the cairo:save function by the push group function, so that any changes to the graphics state will not be visible outside the group.
See also:
#2025-1-2
Function cairo:pop-group-to-source (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Terminates the redirection begun by a call to the cairo:push-group or cairo:push-group-with-content function 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:
(setf group (cairo:pop-group cr))
(setf (cairo:source cr) group)
(cairo:pattern-destroy group)  
But this function is more convenient as their is no need for a variable to store the pattern.

The cairo:pop-group-to-source function calls the cairo:restore function, balancing a call to the cairo:save function by the push group function, so that any changes to the graphics state will not be visible outside the group.
See also:
#2025-1-2
Function cairo:group-target (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The cairo:surface-t instance with the target surface. This object is owned by Cairo. To keep a reference to it, you must call the cairo:surface-reference function.
Details:
Gets the current destination surface for the Cairo context. This is either the original target surface as passed to the cairo:create function or the target surface for the current group as started by the most recent call to the cairo:push-group or cairo:push-group-with-content functions.

This function will always return a valid surface, but the result can be a "nil" surface if cr is already in an error state. A "nil" surface is indicated by a value not equal to the :success value of the cairo:status-t enumeration.
See also:
#2025-1-2
Function cairo:set-source-rgb (cr red green blue)
Arguments:
cr -- a cairo:context-t instance
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
Details:
Sets the source pattern within the Cairo context 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.0 to 1.0. 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
(cairo:set-source-rgb cr 0.0 0.0 0.0)  
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-2
Function cairo:set-source-rgba (cr red green blue alpha)
Arguments:
cr -- a cairo:context-t instance
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
Sets the source pattern within the Cairo context 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.0 to 1.0. 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
(cairo:set-source-rgba cr 0.0 0.0 0.0 1.0)  
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-2
Function cairo:source (cr)
Syntax:
(cairo:source cr) => source
(setf (cairo:source cr) source)
Arguments:
cr -- a cairo:context-t instance
source -- a cairo:pattern-t instance to be used as the source for subsequent drawing operations
Details:
The cairo:source function gets the current source pattern for cr. This object is owned by Cairo. To keep a reference to it, you must call the cairo:pattern-reference function.

The (setf cairo:source) function sets the source pattern within cr to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.

The default source pattern is a solid pattern that is opaque black, that is, it is equivalent to
(cairo:set-source-rgb cr 0.0 0.0 0.0)  
Notes:
The current transformation matrix (CTM) of the pattern will be locked to the user space in effect at the time of the call of the (setf cairo:source) function. This means that further modifications of the CTM will not affect the source pattern. See the cairo:pattern-matrix function.
See also:
2025-1-2
Function cairo:set-source-surface (cr surface x y)
Arguments:
cr -- a cairo:context-t instance
surface -- a cairo:surface-t instance to be used to set the source pattern
x -- a number for the user-space x coordinate of the surface origin
y -- a number for the user-space y coordinate of the surface origin
Details:
This is a convenience function for creating a pattern from surface and setting it as the source in cr with the cairo:source function.

The x and y arguments give the user-space coordinate at which the surface origin should appear. The surface origin is its upper-left corner before any transformation has been applied. The x and y arguments are negated and then set as translation values in the pattern matrix.

Other than the initial translation pattern matrix, as described above, all other pattern attributes, such as its extend mode, are set to the default values as in the cairo:pattern-create-for-surface function. The resulting pattern can be queried with the cairo:source function so that these attributes can be modified if desired, for example, to create a repeating pattern with with the cairo:pattern-extend function.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-2
Function cairo:antialias (cr)
Syntax:
(cairo:antialias context) => antialias
(setf (cairo:antialias context) antialias)
Arguments:
cr -- a cairo:context-t instance
antialias -- a cairo:antialias-t value
Details:
The cairo:antialias function gets the current shape antialiasing mode of the rasterizer used for drawing shapes. The (setf cairo:antialias) function sets the antialiasing mode. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports the :subpixel mode when drawing shapes.
Notes:
This option does not affect text rendering, instead see the cairo:font-options-antialias function.
See also:
2025-1-2
Function cairo:dash (cr)
Syntax:
(cairo:dash cr) => dashes, offset
(setf (cairo:dash cr offset) dashes)
Arguments:
cr -- a cairo:context-t instance
dashes -- a list of numbers coerced to double floats specifying alternate lengths of on and off stroke portions
offset -- a number coerced to a double float for an offset into the dash pattern at which the stroke should start
Details:
The cairo:dash function gets the current dash list to be used by the cairo:stroke function. The (setf cairo:dash) function sets the dash pattern. A dash pattern is specified by dashes, a list 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 :round or :square in order to distributed dots or squares along a path.

If the dashes argument is an empty list dashing is disabled. If the dashes argument has one list element 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 cr will be put into an error state with a status of :invalid-dash.
Notes:
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 the call of the (setf cairo:dash) function.
See also:
2025-1-2
Function cairo:dash-count (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The integer with the length of the dash list, or 0 if no dash list is set.
Details:
This function returns the length of the dash list in cr, 0 if dashing is not currently in effect. See also the cairo:dash function.
See also:
2025-1-2
Function cairo:fill-rule (cr)
Syntax:
(cairo:fill-rule cr) => rule
(setf (cairo:fill-rule cr) rule)
Arguments:
cr -- a cairo:context-t instance
rule -- a cairo:fill-rule-t value for the fill rule
Details:
The cairo:fill-rule function gets the current fill rule within the Cairo context. The (setf cairo:fill-rule) function sets the current fill rule.

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 the cairo:fill and cairo:clip functions. See the cairo:fill-rule-t enumeration for details on the semantics of each available fill rule.

The default fill rule is the :winding value.
See also:
2025-1-2
Function cairo:line-cap (cr)
Syntax:
(cairo:line-cap cr) => cap
(setf (cairo:line-cap cr) cap)
Arguments:
cr -- a cairo:context-t instance
cap -- a cairo:line-cap-t value for the line cap style
Details:
The cairo:line-cap function gets the current line cap style within the Cairo context. The (setf cairo:line-cap) function sets the current line cap style. See the cairo:line-cap-t enumeration 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 the cairo:stroke and cairo:stroke-extents functions, but does not have any effect during path construction.

The default line cap style is the :butt value.
See also:
2025-1-2
Function cairo:line-join (cr)
Syntax:
(cairo:line-join cr) => join
(setf (cairo:line-join cr) join)
Arguments:
cr -- a cairo:context-t instance
join -- a cairo:line-join-t value for the line join style
Details:
The cairo:line-join funcion gets the current line join style within the Cairo context. The (setf cairo:line-join) function sets the current line join style. See the cairo:line-join-t enumeration 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 the cairo:stroke and cairo:stroke-extents functions, but does not have any effect during path construction.

The default line join style is the :miter value.
See also:
2025-1-2
Function cairo:line-width (cr)
Syntax:
(cairo:line-width cr) => width
(setf (cairo:line-width cr) width)
Arguments:
cr -- a cairo:context-t instance
width -- a number coerced to a double float for the line width
Details:
The cairo:line-width function returns the current line width value within the Cairo context. The (setf cairo:line-width) function sets the current line width. Note that the value is unchanged even if the current transformation matrix (CTM) has changed between the calls to the cairo:line-width and (setf cairo:line-width) functions.

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 current transformation matrix (CTM).

As with the other stroke parameters, the current line width is examined by the cairo:stroke and cairo:stroke-extents functions, but does not have any effect during path construction.

The default line width value is 2.0.
Notes:
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 the (setf cairo:line-width) function. The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to the (setf cairo:line-width) function and the stroking operation, then one can just pass user-space values to the (setf cairo:line-width) function and ignore this note.
See also:
2025-1-2
Function cairo:hairline (cr)
Syntax:
(cairo:hairline cr) => setting
(setf (cairo:hairline cr) setting)
Arguments:
cr -- a cairo:context-t instance
setting -- a boolean whether hairline mode is set
Details:
The cairo:hairline function returns whether or not hairline mode is set within the Cairo context. The (setf cairo:hairline) functon sets lines to be hairlines. Hairlines are logically zero-width lines that are drawn at the thinnest renderable width possible in the current Cairo context.

On surfaces with native hairline support, the native hairline functionality will be used. Surfaces that support hairlines include:
pdf/ps
Encoded as 0-width line.
win32_printing
Rendered with the PS_COSMETIC pen.
svg
Encoded as 1 px non-scaling-stroke.
script
Encoded with the set-hairline function.
Cairo will always render hairlines at 1 device unit wide, even if an anisotropic scaling was applied to the stroke width. In the wild, handling of this situation is not well-defined. Some PDF, PS, and SVG renderers match the output of Cairo, but some very popular implementations (Acrobat, Chrome, rsvg) will scale the hairline unevenly. As such, best practice is to reset any anisotropic scaling before calling the cairo:stroke function. See Ellipses With Uniform Stroke Width for an example.

Since 1.18
See also:
2025-1-2
Function cairo:miter-limit (cr)
Syntax:
(cairo:miter-limit cr) => limit
(setf (cairo:miter-limit cr) limit)
Arguments:
cr -- a cairo:context-t instance
limit -- a number coerced to a double float for the miter limit
Details:
The cairo:miter-limit function gets the current miter limit within the Cairo context. The (setf cairo:miter-limit) function sets the miter limit.

If the current line join style is set to the :miter value, see the cairo:line-join function, 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 the cairo:stroke and cairo:stroke-extents functions, 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 in radians can be computed as:
(setf limit (/ 1.0d0 (sin (/ angle 2.0d0))))  
See also:
2025-1-2
Function cairo:operator (cr)
Syntax:
(cairo:operator cr) => op
(setf (cairo:operator cr) op)
Arguments:
cr -- a cairo:context-t instance
op -- a compositing operator, specified as a cairo:operator-t value
Details:
The cairo:operator function gets the current compositing operator for a Cairo context to be used for all drawing operations. The (setf cairo:operator) function sets the compositing operator. See the cairo:operator-t enumeration for details on the semantics of each available compositing operator.

The default operator is the :over value.
See also:
2025-1-2
Function cairo:tolerance (cr)
Syntax:
(cairo:tolerance cr) => tolerance
(setf (cairo:tolerance cr) tolerance)
Arguments:
cr -- a cairo:context-t instance
tolerance -- a number coerced to a double float for the tolerance, in device units, typically pixels
Details:
The cairo:tolerance function gets the current tolerance value used when converting paths into trapezoids. The (setf cairo:tolerance) functions sets the tolerance value.

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.
See also:
2025-1-2
Function cairo:clip (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by the cairo:fill function and according to the current fill rule, see the cairo:fill-rule function.

After a call of the cairo:clip function, 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 the cairo:clip function 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 the cairo:clip function within a cairo:save and cairo:restore pair. The only other means of increasing the size of the clip region is the cairo:reset-clip function.
See also:
2025-1-2
Function cairo:clip-preserve (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by the cairo:fill function and according to the current fill rule. See the cairo:fill-rule function.

Unlike the cairo:clip function, the cairo:clip-preserve function 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 the cairo:clip-preserve function 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 the cairo:clip-preserve function within a cairo:save and cairo:restore pair. The only other means of increasing the size of the clip region is the cairo:reset-clip function.
See also:
#2025-1-2
Function cairo:clip-extents (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
x1 -- a number with the left of the resulting extents
y1 -- a number with the top of the resulting extents
x2 -- a number with the right of the resulting extents
y2 -- a number with the bottom of the resulting extents
Details:
Computes a bounding box in user coordinates covering the area inside the current clip.
Notes:
The numbers returned are double floats.
See also:
2025-1-2
Function cairo:in-clip (cr x y)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the point to test
y -- a number for the y coordinate of the point to test
Returns:
True if the point is inside, or false if outside.
Details:
Tests whether the given point is inside the area that would be visible through the current clip, that is, the area that would be filled by a call to the cairo:paint function.

See the cairo:clip and cairo:clip-preserve functions.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-2
Function cairo:reset-clip (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
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 the cairo:reset-clip function as it will cause results unexpected by higher-level code which calls the cairo:clip function. Consider using the cairo:save and cairo:restore functions around the cairo:clip function as a more robust means of temporarily restricting the clip region.
See also:
2025-1-2
Function cairo:copy-clip-rectangle-list (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The current clip region as a list of rectangles in user coordinates. Each rectangle is represented by a list with the x, y, width, height values of the rectangle.
Details:
Gets the current clip region as a list of rectangles in user coordinates. If the clip region cannot be represented as a list of user-space rectangles the nil value is returned.
Examples:
;; Create a recording surface
(cairo:with-recording-surface (surface :color)
  :; Create a context for the recording surface
  (cairo:with-context (context surface)
    ;; Two rectangles
    (cairo:rectangle context 10 10 15 15)
    (cairo:rectangle context 20 20 10 10)
    ;; Clip the context
    (cairo:clip context)
    ;; Get the current clip region
    (cairo:copy-clip-rectangle-list context)))
=> ((10.0d0 10.0d0 15.0d0 10.0d0)
    (10.0d0 20.0d0 20.0d0 5.0d0)
    (20.0d0 25.0d0 10.0d0 5.0d0))    
See also:
2025-1-2
Function cairo:fill (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
A drawing operator that fills the current path according to the current fill rule, each sub-path is implicitly closed before being filled. After the cairo:fill function, the current path will be cleared from the Cairo context. See the cairo:fill-rule and cairo:fill-preserve functions.
See also:
2025-1-2
Function cairo:fill-preserve (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
A drawing operator that fills the current path according to the current fill rule, each sub-path is implicitly closed before being filled. Unlike the cairo:fill function, the cairo:fill-preserve function preserves the path within the Cairo context.

See the cairo:fill-rule and cairo:fill functions.
See also:
2025-1-2
Function cairo:fill-extents (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
x1 -- a number with the left of the resulting extents
y1 -- a number with the top of the resulting extents
x2 -- a number with the right of the resulting extents
y2 -- a number with the bottom of the resulting extents
Details:
Computes a bounding box in user coordinates covering the area that would be affected, the "inked" area, by a cairo:fill operation given the current path and fill parameters. If the current path is empty, returns an empty rectangle. Surface dimensions and clipping are not taken into account.

Contrast with the cairo:path-extents function, which is similar, but returns non-zero extents for some paths with no inked area, such as a simple line segment.

Note that the cairo:fill-extents function must necessarily do more work to compute the precise inked areas in light of the fill rule, so the cairo:path-extents function may be more desirable for sake of performance if the non-inked path extents are desired.

See the cairo:fill, cairo:fill-rule and cairo:fill-preserve functions.
Notes:
The numbers returned are double floats.
See also:
#2025-1-2
Function cairo:in-fill (cr x y)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the point to test
y -- a number for the y coordinate of the point to test
Returns:
True if the point is inside, or false if outside.
Details:
Tests whether the given point is inside the area that would be affected by a cairo:fill operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account.

See the cairo:fill, cairo:fill-rule and cairo:fill-preserve functions.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
#2025-1-2
Function cairo:mask (cr pattern)
Arguments:
cr -- a cairo:context-t instance
pattern -- a cairo:pattern-t instance
Details:
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.
See also:
2025-1-2
Function cairo:mask-surface (cr surface x y)
Arguments:
cr -- a cairo:context-t instance
surface -- a cairo:surface-t instance
x -- a number for the x coordinate at which to place the origin of surface
y -- a number for the y coordinate at which to place the origin of surface
Details:
A drawing operator that paints the current source using the alpha channel of surface as a mask. Opaque areas of surface are painted with the source, transparent areas are not painted.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
#2025-1-2
Function cairo:paint (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
A drawing operator that paints the current source everywhere within the current clip region.
Examples:
Code fragment to paint the background with a given color.
;; Paint the white color on the background
(cairo:set-source-rgb cr 1.0 1.0 1.0)
(cairo:paint cr)    
See also:
2025-1-2
Function cairo:paint-with-alpha (cr alpha)
Arguments:
cr -- a cairo:context-t instance
alpha -- a number coerced to a double float for the alpha value, between 0.0 (transparent) and 1.0 (opaque)
Details:
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 the cairo:paint function, but the drawing is faded out using the alpha value.
See also:
2025-1-2
Function cairo:stroke (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After the cairo:stroke function, the current path will be cleared from the Cairo context. See the cairo:line-width, cairo:line-join, cairo:line-cap, cairo:dash, and cairo:stroke-preserve functions.
Notes:
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 the cairo:dash function. If the cairo:line-cap-t style is :round or :square then these segments will be drawn as circular dots or squares respectively. In the case of :square, the orientation of the squares is determined by the direction of the underlying path.
  2. A sub-path created by the cairo:move-to function followed by either a call to the cairo:close-path function or one or more calls to the cairo:line-to function to the same coordinate as the the cairo:move-to function. If the cairo:line-cap-t style is :round then these sub-paths will be drawn as circular dots. Note that in the case of :square a degenerate sub-path will not be drawn at all, since the correct orientation is indeterminate.
In no case will a cairo:line-cap-t style of :butt cause anything to be drawn in the case of either degenerate segments or sub-paths.
See also:
2025-1-2
Function cairo:stroke-preserve (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike the cairo:stroke function, the cairo:stroke-preserve function preserves the path within the Cairo context.

See the cairo:line-width, cairo:line-join, cairo:line-cap, and cairo:dash functions.
See also:
#2025-1-2
Function cairo:stroke-extents (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
x1 -- a number with the left of the resulting extents
y1 -- a number with the top of the resulting extents
x2 -- a number with the right of the resulting extents
y2 -- a number with the bottom of the resulting extents
Details:
Computes a bounding box in user coordinates covering the area that would be affected, the "inked" area, by a cairo:stroke operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle. Surface dimensions and clipping are not taken into account.

Note that if the line width is set to exactly zero, then the cairo:stroke-extents function will return an empty rectangle. Contrast with the cairo:path-extents function which can be used to compute the non-empty bounds as the line width approaches zero.

Note that the cairo:stroke-extents function must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so the cairo:path-extents function may be more desirable for sake of performance if non-inked path extents are desired.

See the cairo:stroke, cairo:line-width, cairo:line-join, cairo:line-cap, cairo:dash, and cairo:stroke-preserve functions.
Notes:
The numbers returned are double floats.
See also:
#2025-1-2
Function cairo:in-stroke (cr x y)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the point to test
y -- a number for the y coordinate of the point to test
Returns:
True if the point is inside, or false if outside.
Details:
Tests whether the given point is inside the area that would be affected by a cairo:stroke operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account.

See the cairo:stroke, cairo:line-width, cairo:line-join, cairo:line-cap, cairo:dash, and cairo:stroke-preserve functions.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
#2025-1-2
Function cairo:copy-page (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Emits the current page for backends that support multiple pages, but does not clear it, so, the contents of the current page will be retained for the next page too. Use the cairo:show-page function if you want to get an empty page after the emission.

This is a convenience function that simply calls the cairo:surface-copy-page function on the target of cr.
See also:
#2025-1-2
Function cairo:show-page (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Emits and clears the current page for backends that support multiple pages. Use the cairo:copy-page function if you do not want to clear the page.

This is a convenience function that simply calls the cairo:surface-show-page function on the target of cr.
See also:
2025-1-2

Paths

CEnum cairo:path-data-type-t
Declaration:
(cffi:defcenum path-data-type-t
  :move-to
  :line-to
  :curve-to
  :close-path)  
Values:
:move-to
A move-to operation.
:line-to
A line-to operation.
:curve-to
A curve-to operation.
:close-path
A close-path operation.
Details:
The cairo:path-data-type-t enumeration is used to describe the type of one portion of a path when represented as a cairo:path-t instance. See the cairo:path-data-t structure for details.
See also:
2025-1-14
CStruct cairo:path-data-t
Declaration:
(cffi:defcstruct header-t
  (data-type path-data-type-t)
  (length :int))

(cffi:defcstruct point-t (x :double) (y :double))

(cffi:defcunion path-data-t (header (:pointer (:struct header-t))) (point (:pointer (:struct point-t))))
Details:
The cairo:path-data-t structure is used to represent the path data inside a cairo:path-t instance.

The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of cairo:path-data-t instances, which is a union of headers and points.

Each portion of the path is represented by one or more elements in the array, one header followed by 0 or more points. The length value of the header is the number of array elements for the current portion including the header, that is length == 1 + # of points, and where the number of points for each element type is as follows:
:move-to     1 point
:line-to     1 point
:curve-to    3 points
:close-path  0 points  
The semantics and ordering of the coordinate values are consistent with the cairo:move-to, cairo:line-to, cairo:curve-to, and cairo:close-path functions.
Notes:
The Lisp API has the cairo:path-data-to-list function, that returns a cairo:path-data-t instance as a Lisp list. There are no functions available, that allows to create a cairo:path-data-t instance from scratch.
See also:
2025-1-14
CStruct cairo:path-t
Declaration:
(cffi:defcstruct path-t
  (status status-t)
  (data (:pointer (:pointer (:struct path-data-t))))
  (numdata :int))  
Values:
status
The current cairo:status-t value with the error status.
data
The cairo:path-data-t instances in the path.
numdata
The integer with the number of elements in the data array.
Details:
The data structure for holding a path. This data structure serves as the return value for the cairo:copy-path and cairo:copy-path-flat functions as well the input value for the cairo:append-path function. See the cairo:path-data-t documentation for more information.

The numdata member gives the number of elements in the data array. This number is larger than the number of independent path portions, defined in the cairo:path-data-type-t structure, since the data includes both headers and coordinates for each portion.
See also:
2025-1-14
Accessor cairo:path-status (path)
Arguments:
path -- a cairo:path-t instance
Returns:
The current cairo:status-t value with the error status.
Details:
Accessor of the status slot of the cairo:path-t structure.
See also:
2025-1-14
Accessor cairo:path-data (path)
Arguments:
path -- a cairo:path-t instance
Returns:
The cairo:path-data-t instances in the path.
Details:
Accessor of the data slot of the cairo:path-t structure.
See also:
2025-1-14
Accessor cairo:path-numdata (path)
Arguments:
path -- a cairo:path-t instance
Returns:
The integer with the number of elements in the data array.
Details:
Accessor of the numdata slot of the cairo:path-t structure.
See also:
2025-1-14
Function cairo:copy-path (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The cairo:path-t instance with the copy of the current path. The caller owns the returned object and should call the cairo:path-destroy function when finished with it.
Details:
Creates a copy of the current path and returns it to the user as a cairo:path-t instance. See the cairo:path-data-t documentation for more information.

This function will always return a valid path, but the result will have no data, if either of the following conditions hold:
  • If there is insufficient memory to copy the path. In this case the status of the path will be set to the :no-memory value.
  • If cr is already in an error state. In this case the cairo:path-status function will return the same status that would be returned by the cairo:status function.
See also:
2025-1-14
Function cairo:copy-path-flat (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The cairo:path-t instance with the copy of the current path. The caller owns the returned object and should call the cairo:path-destroy function when finished with it.
Details:
Gets a flattened copy of the current path and returns it to the user as a cairo:path-t instance. See the cairo:path-data-t documentation for more information.

This function is like the cairo:copy-path function 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 :curve-to elements which will instead be replaced by a series of :line-to elements.

This function will always return a valid path, but the result will have no data, if either of the following conditions hold:
  • If there is insufficient memory to copy the path. In this case the status of the path will be set to the :no-memory value.
  • If cr is already in an error state. In this case the cairo:path-status function will return the same status that would be returned by the cairo:status function.
See also:
2025-1-14
Function cairo:path-destroy (path)
Arguments:
path -- a cairo:path-t instance previously returned by either the cairo:copy-path or cairo:copy-path-flat functions
Details:
Immediately releases all memory associated with path. After a call to the cairo:path-destroy function the path is no longer valid and should not be used further.
See also:
2025-1-14
Function cairo:path-data-to-list (path)
Arguments:
path -- a cairo:path-t instance
Returns:
The list with the path.
Details:
Creates a list with the path information from a cairo:path-t instance. See the cairo:copy-path and cairo:copy-path-flat functions.
Notes:
There is no Lisp API exported that gives direct access to the internal path data, nor has the Lisp API functions to create from scratch path data information.
Examples:
(cairo:with-recording-surface (surface :color)
  (cairo:with-context (context surface)
    (cairo:new-path context)
    (cairo:rectangle context 10 20 30 40)
    (let ((path (cairo:copy-path-flat context)))
      (prog1
        (cairo:path-data-to-list path)
        (cairo:path-destroy path)))))
=> (:PATH
    (:MOVE-TO 10.0d0 20.0d0)
    (:LINE-TO 40.0d0 20.0d0)
    (:LINE-TO 40.0d0 60.0d0)
    (:LINE-TO 10.0d0 60.0d0)
    (:CLOSE-PATH)
    (:MOVE-TO 10.0d0 20.0d0))    
See also:
2025-1-14
Function cairo:append-path (cr path)
Arguments:
cr -- a cairo:context-t instance
path -- a cairo:path-t instance to be appended
Details:
Append path onto the current path. The path may be either the return value from one of the cairo:copy-path or cairo:copy-path-flat functions.
See also:
2025-1-14
Function cairo:has-current-point (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
The boolean whether a current point is defined.
Details:
Returns whether a current point is defined on the current path. See the cairo:current-point function for details on the current point.
See also:
2025-1-14
Function cairo:current-point (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
x -- a double float with the x coordinate of the current point
y -- a double float with the y coordinate of the current point
Details:
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 the cairo:has-current-point function.

Most path construction functions alter the current point. See the following functions for details on how they affect the current point:
new-path          new-sub-path      append-path
close-path        move-to           line-to
curve-to          rel-move-to       rel-line-to
rel-curve-to      arc               arc-negative
rectangle         text-path         glyph-path  
Some functions use and alter the current point but do not otherwise change the current path:
show-text  
Some functions unset the current path and as a result, the current point:
fill     stroke  
See also:
2025-1-14
Function cairo:new-path (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
Clears the current path. After this call there will be no path and no current point.
See also:
2025-1-14
Function cairo:new-sub-path (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
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 the cairo:move-to function.

A call to the cairo:new-sub-path function is particularly useful when beginning a new sub-path with one of the cairo:arc calls. This makes things easier as it is no longer necessary to manually compute the initial coordinates of the arc for a call to the cairo:move-to function.
See also:
2025-1-14
Function cairo:close-path (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
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 the cairo:move-to function, and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path.

The behavior of the cairo:close-path function is distinct from simply calling the cairo:line-to function 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 the cairo:close-path function, this function will have no effect.
Notes:
Any call to the cairo:close-path function will place an explicit :move-to element into the path immediately after the :close-path element, which can be seen in the cairo:copy-path function 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 element immediately after the :close-path element will provide that point.
See also:
2025-1-14
Function cairo:path-extents (cr)
Arguments:
cr -- a cairo:context-t instance
Returns:
x1 -- a number for the left of the resulting extents
y1 -- a number for the top of the resulting extents
x2 -- a number for the right of the resulting extents
y2 -- a number for the bottom of the resulting extents
Details:
Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle. Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.

Contrast with the cairo:fill-extents and cairo:stroke-extents functions which return the extents of only the area that would be "inked" by the corresponding drawing operations.

The result of the cairo:path-extents function is defined as equivalent to the limit of the cairo:stroke-extents function with the :round value as the line width approaches 0.0, but never reaching the empty-rectangle returned by the cairo:stroke-extents function for a line width of 0.0.

Specifically, this means that zero-area sub-paths such as cairo:move-to, cairo:line-to segments, even degenerate cases where the coordinates to both calls are identical, will be considered as contributing to the extents. However, a lone cairo:move-to will not contribute to the results of the cairo:path-extents function.
Notes:
The numbers returned are double floats.
See also:
2025-1-14
Function cairo:move-to (cr x y)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the new position
y -- a number for the y coordinate of the new position
Details:
Begin a new sub-path. After this call the current point will be (x,y).
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:rel-move-to (cr dx dy)
Arguments:
cr -- a cairo:context-t instance
dx -- a number for the x offset
dy -- a number for the y offset
Details:
Begin a new sub-path. After this call the current point will offset by (dx,dy).

Given a current point of (x,y),
(cairo:rel-move-to cr dx dy)  
is logically equivalent to
(cairo:move-to cr (+ x dx) (+ y dy))  
It is an error to call this function with no current point. Doing so will cause cr to shutdown with a :no-current-point status.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:line-to (cr x y)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the end of the new line
y -- a number for the y coordinate of the end of the new line
Details:
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 the cairo:line-to function this function will behave as:
(cairo:move-to cr x y)  
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:rel-line-to (cr dx dy)
Arguments:
cr -- a cairo:context-t instance
dx -- a number for the x offset to the end of the new line
dy -- a number for the y offset to the end of the new line
Details:
Relative-coordinate version of the cairo:line-to function. 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),
(cairo:rel-line-to cr dx dy)  
is logically equivalent to
(cairo:line-to cr (+ x dx) (+ y dy))  
It is an error to call this function with no current point. Doing so will cause cr to shutdown with a :no-current-point status.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:curve-to (cr x1 y1 x2 y2 x3 y3)
Arguments:
cr -- a cairo:context-t instance
x1 -- a number for the x coordinate of the first control point
y1 -- a number for the y coordinate of the first control point
x2 -- a number for the x coordinate of the second control point
y2 -- a number for the y coordinate of the second control point
x3 -- a number for the x coordinate of the third control point
y3 -- a number for the y coordinate of the third control point
Details:
Adds a cubic Bezier 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 the cairo:curve-to function this function will behave as if preceded by a call to:
(cairo:move-to cr x1 y1)  
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:rel-curve-to (cr dx1 dy1 dx2 dy2 dx3 dy3)
Arguments:
cr -- a cairo:context-t instance
dx1 -- a number for the x offset to the first control point
dy1 -- a number for the y offset to the first control point
dx2 -- a number for the x offset to the second control point
dy2 -- a number for the y offset to the second control point
dx3 -- a number for the x offset to the end of the curve
dy3 -- a number for the y offset to the end of the curve
Details:
Relative-coordinate version of the cairo:curve-to function. 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),
(cairo:rel-curve-to cr dx1 dy1 dx2 dy2 dx3 dy3)  
is logically equivalent to
(cairo:curve-to cr (+ 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 cr to shutdown with a :no-current-point status.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:rectangle (cr x y width height)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x coordinate of the top left corner of the rectangle
y -- a number for the y coordinate to the top left corner of the rectangle
width -- a number for the width of the rectangle
height -- a number for the height of the rectangle
Details:
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:
(cairo:move-to cr x y)
(cairo:rel-line-to cr width 0)
(cairo:rel-line-to cr 0 height)
(cairo:rel-line-to cr (- width) 0)
(cairo:close-path cr)  
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:arc (cr x y radius angle1 angle2)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x position of the center of the arc
y -- a number for the y position of the center of the arc
radius -- a number for the radius of the arc
angle1 -- a number for the start angle, in radians
angle2 -- a number for the end angle, in radians
Details:
Adds a circular arc of the given radius to the current path. The arc is centered at (x,y), 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*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 the cairo:new-sub-path function before calling the cairo:arc function.

Angles are measured in radians. An angle of 0 is in the direction of the positive X axis (in user space). An angle of PI/2 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.

This function gives the arc in the direction of increasing angles. See the cairo:arc-negative function to get the arc in the direction of decreasing angles.
Examples:
The arc is circular in user space. To achieve an elliptical arc, you can scale the current coordinate transformation matrix (CTM) by different amounts in the x and y directions. For example, to draw an ellipse in the box given by x, y, width, height:
(cairo:save cr)
(cairo:translate cr (+ x (/ width 2)) (+ y (/ height 2)))
(cairo:scale cr (/ width 2) (/ height 2))
(cairo:arc cr 0 0 1 0 (* 2 pi))
(cairo:restore cr)    
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:arc-negative (cr x y radius angle1 angle2)
Arguments:
cr -- a cairo:context-t instance
x -- a number for the x position of the center of the arc
y -- a number for the y position of the center of the arc
radius -- a number for the radius of the arc
angle1 -- a number for the start angle, in radians
angle2 -- a number for the end angle, in radians
Details:
Adds a circular arc of the given radius to the current path. The arc is centered at (x,y), 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*PI until it is less than angle1.

See the cairo:arc function for more details. This function differs only in the direction of the arc between the two angles.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:glyph-path (cr glyphs)
Arguments:
cr -- a cairo:context-t instance
glyphs -- a list of glyphs, each glyph is represented by an item that is a list with the (index x y) glyph values
index -- an unsigned integer for the glyph index in the font
x -- a number coerced to a double float for the offset in the x direction between the origin used for drawing the string and the orgin of this glyph
y -- a number coerced to a double float for the y direction between the orgin used for drawing the string and the origin of this glyph
Details:
Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of the cairo:show-glyphs function.
Examples:
Get and return the path for the glyph representing the #\0 character.
(cairo:with-context-for-recording-surface (context :color)
  (cairo:glyph-path context '((20 0 10))) ; #\0
  (cairo:path-data-to-list (cairo:copy-path context)))
=>
(:PATH (:MOVE-TO 3.7265625d0 10.0d0)
       (:LINE-TO 2.84765625d0 10.0d0)
       (:LINE-TO 2.84765625d0 4.3984375d0)
       (:CURVE-TO 2.63671875d0 4.6015625d0
                  2.359375d0 4.8046875d0
                  2.015625d0 5.00390625d0)
       (:CURVE-TO 1.671875d0 5.20703125d0
                  1.36328125d0 5.359375d0
                  1.08984375d0 5.4609375d0)
       (:LINE-TO 1.08984375d0 4.609375d0)
       (:CURVE-TO 1.58203125d0 4.37890625d0
                  2.01171875d0 4.09765625d0
                  2.37890625d0 3.76953125d0)
       (:CURVE-TO 2.74609375d0 3.44140625d0
                  3.0078125d0 3.12109375d0
                  3.16015625d0 2.8125d0)
       (:LINE-TO 3.7265625d0 2.8125d0)
       (:CLOSE-PATH)
       (:MOVE-TO 3.7265625d0 10.0d0))    
See also:
2025-1-14
Function cairo:text-path (cr uft8)
Arguments:
cr -- a cairo:context-t instance
utf8 -- a string of text encoded in UTF-8, or nil
Details:
Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of the cairo:show-text function. Text conversion and positioning is done similar to the cairo:show-text function.

Like the cairo:show-text function, 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 chaining multiple calls to to the cairo:text-path function without having to set the current point in between.
Notes:
The cairo:text-path 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 the cairo:glyph-path function for the "real" text path API in Cairo.
See also:
2025-1-14

Introduction to pattern

The cairo:pattern-t structure is the paint with which Cairo draws. The primary use of patterns is as the source for all Cairo drawing operations, although they can also be used as masks, that is, as the brush too. A Cairo pattern is created by using one of the many constructors, of the form cairo:pattern-create-type or implicitly through the cairo:set-source-type functions.

Types and functions for pattern

CEnum cairo:extend-t
Declaration:
(cffi:defcenum extend-t
  :none
  :repeat
  :reflect
  :pad)  
Values:
:none
Pixels outside of the source pattern are fully transparent.
:repeat
The pattern is tiled by repeating.
:reflect
The pattern is tiled by reflecting at the edges.
:pad
Pixels outside of the pattern copy the closest pixel from the source.
Details:
The cairo:extend-t enumeration is used to describe how pattern color/alpha will be determined for areas "outside" the natural area, of the pattern 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.
See also:
2025-1-14
CEnum cairo:filter-t
Declaration:
(cffi:defcenum filter-t
  :fast
  :good
  :best
  :nearest
  :bilinear
  :gaussian)  
Values:
:fast
A high-performance filter, with quality similar to :nearest.
:good
A reasonable-performance filter, with quality similar to :bilinear.
:best
The highest-quality available, performance may not be suitable for interactive use.
:nearest
Nearest-neighbor filtering.
:bilinear
Linear interpolation in two dimensions.
:gaussian
This filter value is currently unimplemented, and should not be used in current code.
Details:
The cairo:filter-t enumeration is used to indicate what filtering should be applied when reading pixel values from patterns. See the cairo:pattern-filter function for indicating the desired filter to be used with a particular pattern.
See also:
2025-1-14
CEnum cairo:pattern-type-t
Declaration:
(cffi:defcenum pattern-type-t
  :solid
  :surface
  :linear
  :radial
  :mesh
  :raster-source)  
Values:
:solid
The pattern is a solid (uniform) color. It may be opaque or translucent.
:surface
The pattern is a based on a surface (an image).
:linear
The pattern is a linear gradient.
:radial
The pattern is a radial gradient.
:mesh
The pattern is a mesh.
:raster-source
The pattern is a user pattern providing raster data.
Details:
The cairo:pattern-type-t enumeration 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 cairo:pattern-create-rgb and cairo:pattern-create-rgba functions create :solid patterns. The remaining cairo:pattern-create-type functions map to pattern types in obvious ways. The pattern type can be queried with the cairo:pattern-type function.

Most Cairo 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 are the cairo:pattern-add-color-stop-rgb and cairo:pattern-add-color-stop-rgba functions which must only be called with gradient patterns, either :linear or :radial. Otherwise the pattern will be shutdown and put into an error state.
See also:
2025-1-14
CStruct cairo:pattern-t
Details:
The cairo:pattern-t structure represents a source when drawing onto a surface. There are different subtypes of cairo:pattern-t structures, for different types of sources, for example, the cairo:pattern-create-rgb function creates a pattern for a solid opaque color.

Other than various cairo:pattern-create-type functions, some of the pattern types can be implicitly created using various cario:set-source-type functions, for example the cairo:set-source-rgb function.

The type of a pattern can be queried with the cairo:pattern-type function.

Memory management of the cairo:pattern-t structure is done with the cairo:pattern-reference and cairo:pattern-destroy functions.
See also:
2025-1-14
Function cairo:pattern-reference (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The referenced cairo:pattern-t instance.
Details:
Increases the reference count on pattern by one. This prevents pattern from being destroyed until a matching call to the cairo:pattern-destroy function is made.

The number of references to a cairo:pattern-t can be get using the cairo:pattern-reference-count function.
See also:
2025-1-14
Function cairo:pattern-reference-count (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The unsigned integer with the current reference count of pattern.
Details:
Returns the current reference count of pattern. If the instance is a "nil" pattern, 0 will be returned.
See also:
2025-1-14
Function cairo:pattern-destroy (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Details:
Decreases the reference count on pattern by one. If the result is zero, then pattern and all associated resources are freed. See the cairo:pattern-reference function.
See also:
2025-1-14
Function cairo:pattern-status (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The cairo:status-t value.
Details:
Checks whether an error has previously occurred for this pattern. Possible values are :success, :no-memory, :invalid-matrix, :pattern-type-mismatch, or :invalid-mesh-construction.
See also:
2025-1-14
Function cairo:pattern-type (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
Details:
This function returns the type of a pattern. See the cairo:pattern-type-t enumeration for available types.
See also:
2025-1-14
Function cairo:pattern-extend (pattern)
Syntax:
(cairo:pattern-extend pattern) => extend
(setf (cairo:pattern-extend pattern) extend)
Arguments:
pattern -- a cairo:pattern-t instance
extend -- a cairo:extend-t value describing how the area outside of the pattern will be drawn
Details:
The cairo:pattern-extend function gets the current extend mode for a pattern. The (setf cairo:pattern-extend) function sets the mode to be used for drawing outside the area of a pattern. See the cairo:extend-t enumeration for details on the semantics of each extend strategy.

The default extend mode is :none for surface patterns and :pad for gradient patterns.
See also:
2025-1-14
Function cairo:pattern-filter (pattern)
Syntax:
(cairo:pattern-filter pattern) => filter
(setf (cairo:filter-extend pattern) filter)
Arguments:
pattern -- a cairo:pattern-t instance
filter -- a cairo:filter-t value describing the filter to use for resizing the pattern
Details:
The cairo:pattern-filter function gets the current filter for pattern. The (setf cairo:pattern-filter) function sets the filter to be used for resizing when using the pattern. See the cairo:filter-t enumeration for details on each filter.

Note that you might want to control filtering even when you do not have an explicit cairo:pattern-t instance, for example when using the cairo:set-source-surface function. In these cases, it is convenient to use the cairo:source function to get access to the pattern that Cairo creates implicitly. For example:
(cairo:set-source-surface context image x y)
(setf (cairo:pattern-filter (cairo:source cr)) :nearest)  
See also:
2025-1-14
Function cairo:pattern-matrix (pattern matrix)
Syntax:
(cairo:pattern-matrix pattern matrix) => matrix
(setf (cairo:filter-matrix pattern) matrix)
Arguments:
pattern -- a cairo:pattern-t instance
matrix -- a cairo:matrix-t instance
Details:
The cairo:pattern-matrix function gets the transformation matrix of the pattern. The (setf cairo:pattern-matrix) function sets the transformation matrix to matrix. This matrix 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.

Important: Please 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 in that 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 the correct code to use is:
(cairo:matrix-init-scale matrix 0.5 0.5)
(setf (cairo:pattern-matrix pattern) matrix)  
Meanwhile, using values of 2.0 rather than 0.5 in the code above would cause the pattern to appear at half of its default size.

Also, please note the discussion of the user-space locking semantics of the cairo:source function.
See also:
2025-1-14
Function cairo:pattern-add-color-stop-rgb (pattern offset red green blue)
Arguments:
pattern -- a cairo:pattern-t instance
offset -- a number for an offset in the range [0.0 .. 1.0]
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
Details:
Adds an opaque color stop to a gradient pattern. The offset specifies the location along the gradient's control vector. For example, a linear control vector of the pattern is from (x0,y0) to (x1,y1) while a radial control vector of the pattern 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 the cairo:set-source-rgb function.

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.
Notes:
If the pattern argument is not a gradient pattern, for example a linear or radial pattern, then pattern will be put into an error status with a status of :pattern-type-mismatch.
Lisp implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:pattern-add-color-stop-rgba (pattern offset red green blue alpha)
Arguments:
pattern -- a cairo:pattern-t instance
offset -- a number for an offset in the range [0.0 .. 1.0]
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
Adds a translucent color stop to a gradient pattern. The offset specifies the location along the control vector of the gradient. For example, a linear control vector of the gradient is from (x0,y0) to (x1,y1) while a radial control vector of the gradient 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 the cairo:set-source-rgba function.

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.
Notes:
If the pattern argument is not a gradient pattern, for example a linear or radial pattern, then pattern will be put into an error status with a :pattern-type-mismatch status.
Lisp implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:pattern-color-stop-count (cr)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The integer with the number of color stops.
Details:
Gets the number of color stops specified in the given gradient pattern. Returns nil if pattern is not a gradient pattern.
See also:
2025-1-14
Function cairo:pattern-color-stop-rgba (pattern index)
Arguments:
pattern -- a cairo:pattern-t instance
index -- an integer for the index of the stop to return data for
Returns:
offset -- a number for the offset of the stop
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
Gets the color and offset information at the given index for a gradient pattern. Returns nil if pattern is not a gradient pattern of if index is not valid for the given pattern.

Values of index are 0 to 1 less than the number returned by the cairo:pattern-color-stop-count function.
Notes:
The numbers returned are double floats.
See also:
2025-1-14
Function cairo:pattern-create-rgb (red green blue)
Arguments:
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory.
Details:
Creates a new cairo:pattern-t instance corresponding to an opaque color. The caller owns the returned object and should call the cairo:pattern-destroy function when finished with it. This function will always return a valid pattern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.

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.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:pattern-create-rgba (red green blue alpha)
Arguments:
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory.
Details:
Creates a new cairo:pattern-t instance corresponding to a translucent color. The caller owns the returned object and should call the cairo:pattern-destroy function when finished with it. This function will always return a valid pattern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.

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.
Notes:
The numbers for the arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-14
Function cairo:pattern-rgba (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
Gets the color for a solid color pattern. Returns nil if the pattern ist not a solid color pattern.
Notes:
The numbers returned are double floats.
See also:
2025-1-19
Function cairo:pattern-create-for-surface (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory. The caller owns the returned object and should call the cairo:pattern-destroy function when finished with it.
Details:
Create a new cairo:pattern-t instance for the given surface. This function will always return a valid pattern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.
See also:
2025-1-19
Function cairo:pattern-surface (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The cairo:surface-t instance of the pattern.
Details:
Gets the surface of a surface pattern. Returns nil if the pattern is not a surface pattern.

The reference returned in surface is owned by the pattern. The caller should call the cairo:surface-reference function if the surface is to be retained.
See also:
2025-1-19
Function cairo:pattern-create-linear (x0 y0 x1 y1)
Arguments:
x0 -- a number for the x coordinate of the start point
y0 -- a number for the y coordinate of the start point
x1 -- a number for the x coordinate of the end point
y1 -- a number for the y coordinate of the end point
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory. The caller owns the returned instance and should call the cairo:pattern-destroy function when finished with it.
Details:
Create a new linear gradient cairo:pattern-t instance along the line defined by (x0,y0) and (x1,y1). This function will always return a valid patttern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.

Before using the gradient pattern, a number of color stops should be defined using the cairo:pattern-add-color-stop-rgb or cairo:pattern-add-color-stop-rgba functions.
Notes:
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 the cairo:pattern-matrix function.
Lisp implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-19
Function cairo:pattern-linear-points (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
x0 -- a number for the x coordinate of the first point
y0 -- a number for the y coordinate of the first point
y0 -- a number for the x coordinate of the second point
y1 -- a number for the y coordinate of the second point
Details:
Gets the gradient endpoints for a linear gradient. Returns nil if the pattern is not a linear gradient pattern.
Notes:
The numbers returned are double floats.
See also:
2025-1-19
Function cairo:pattern-create-radial (x0 y0 r0 x1 y1 r1)
Arguments:
x0 -- a number for the x coordinate for the center of the start circle
y0 -- a number for the y coordinate for the center of the start circle
r0 -- a number for the radius of the start circle
x1 -- a number for the x coordinate for the center of the end circle
y1 -- a number for the y coordinate for the center of the end circle
r1 -- a number for the radius of the end circle
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory. The caller owns the returned object and should call the cairo:pattern-destroy function when finished with it.
Details:
Creates a new radial gradient cairo:pattern-t instance between the two circles defined by x0,y0,r0) and (x1,y1,r1). This function will always return a valid pattern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.

Before using the gradient pattern, a number of color stops should be defined using the cairo:pattern-add-color-stop-rgb or cairo:pattern-add-color-stop-rgba functions.
Notes:
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 the cairo:pattern-matrix function.
Lisp implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-19
Function cairo:pattern-radial-circles (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
x0 -- a number with the x coordinate for the center of the first circle
y0 -- a number with the y coordinate for the center of the first circle
r0 -- a number with the radius for the first circle
x1 -- a number with the x coordinate for the center of the second circle
y1 -- a numbe with the y coordinate for the center of the second circle
r1 -- a number with the radius for the second circle
Details:
Gets the gradient endpoint circles for a radial gradient, each specified as a center coordinate and a radius. Returns nil it the pattern is not a radial gradient pattern.
Notes:
The numbers returned a double floats.
See also:
2025-1-19
Function cairo:pattern-create-mesh ()
Returns:
The newly created cairo:pattern-t instance if successful, or an error pattern in case of no memory. The caller owns the returned object and should call the cairo:pattern-destroy function when finished with it.
Details:
Create a new mesh pattern. This function will always return a valid pattern, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use the cairo:pattern-status function.

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 :invalid-mesh-construction value.

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.
      C1     Side 1       C2
       +---------------+
       |               |
       |  P1       P2  |
       |               |
Side 0 |               | Side 2
       |               |
       |               |
       |  P0       P3  |
       |               |
       +---------------+
     C0     Side 3        C3  
Each patch is constructed by first calling the cairo:mesh-pattern-begin-patch function, then the cairo:mesh-pattern-move-to to specify the first point in the patch C0. Then the sides are specified with calls to the cairo:mesh-pattern-curve-to and cairo:mesh-pattern-line-to functions.

The four additional control points (P0,P1,P2,P3) in a patch can be specified with the cairo:mesh-pattern-set-control-point function.

At each corner of the patch (C0,C1,C2,C3) a color may be specified with the cairo:mesh-pattern-set-corner-color-rgb or cairo:mesh-pattern-set-corner-color-rgba functions. 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, that is, 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, that is, 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 the cairo:mesh-pattern-end-patch function 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 the cairo:mesh-pattern-begin-patch and cairo:mesh-pattern-end-patch functions.

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 2. 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.
Notes:
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 the cairo:pattern-matrix function.
Examples:
;; Add a Coons patch
(let ((pattern (cairo:pattern-create-mesh)))
  ...
  ;; Start the patch
  (cairo:mesh-pattern-begin-patch pattern)
  ;; Set the path
  (cairo:mesh-pattern-move-to pattern 0 0)
  (cairo:mesh-pattern-curve-to pattern 30 -30 60 30 100 0)
  (cairo:mesh-pattern-curve-to pattern 60 30 130 60 100 100)
  (cairo:mesh-pattern-curve-to pattern 60 70 30 130 0 100)
  (cairo:mesh-pattern-curve-to pattern 30 70 -30 30 0 0)
  ;; Set the colors
  (cairo:mesh-pattern-set-corner-color-rgb pattern 0 1 0 0)
  (cairo:mesh-pattern-set-corner-color-rgb pattern 1 0 1 0)
  (cairo:mesh-pattern-set-corner-color-rgb pattern 2 0 0 1)
  (cairo:mesh-pattern-set-corner-color-rgb pattern 3 1 1 0)
  ;; Stop the patch
  (cairo:mesh-pattern-end-patch pattern)
  ...
  )

;; Add a Gouraud-shaded triangle (let ((pattern (cairo:pattern-create-mesh))) ... ;; Start the patch (cairo:mesh-pattern-begin-patch pattern) ;; Set the path (cairo:mesh-pattern-move-to pattern 100 100) (cairo:mesh-pattern-line-to patten 130 130) (cairo:mesh-pattern-line-to pattern 130 70) ;; Set the colors (cairo:mesh-pattern-set-corner-color-rgb pattern 0 1 0 0) (cairo:mesh-pattern-set-corner-color-rgb pattern 1 0 1 0) (cairo:mesh-pattern-set-corner-color-rgb pattern 2 0 0 1) ;; Stop the patch (cairo:mesh-pattern-end-patch pattern) ... )
See also:
2025-1-19
Function cairo:mesh-pattern-begin-patch (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Details:
Begin a patch in a mesh pattern. After calling this function, the patch shape should be defined with the cairo:mesh-pattern-move-to, cairo:mesh-pattern-line-to and cairo:mesh-pattern-curve-to functions.

After defining the patch, the cairo:mesh-pattern-end-patch function must be called before using the pattern as a source or mask.
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If pattern already has a current patch, it will be put into an error status with a :invalid-mesh-contstruction value.
See also:
2025-1-19
Function cairo:mesh-pattern-end-patch (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Details:
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 the cairo:mesh-pattern-line-to function was used.
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If pattern has no current patch or the current patch has no current point, pattern will be put into an error status with a :invalid-mesh-construction value.
See also:
2025-1-19
Function cairo:mesh-pattern-move-to (pattern x y)
Arguments:
pattern -- a cairo:pattern-t instance
x -- a number coerced to a double float for the x coordinate of the new position
y -- a number coerced to a double float for the y coordinate of the new position
Details:
Define the first point of the current patch in a mesh pattern. After this call the current point will be (x,y).
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. 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 :invalid-mesh-construction value.
See also:
2025-1-19
Function cairo:mesh-pattern-line-to (pattern x y)
Arguments:
pattern -- a cairo:pattern-t instance
x -- a number coerced to a double float for the x coordinate of the end of the new line
y -- a number coerced to a double float for the y coordinate of the end of the new line
Details:
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 the cairo:mesh-pattern-line-to function this function will behave as
(cairo:mesh-pattern-move-to pattern x y)  
After this call the current point will be (x,y).
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a :invalid-mesh-construction value.
See also:
2025-1-19
Function cairo:mesh-pattern-curve-to (pattern x1 y1 x2 y2 x3 y3)
Arguments:
pattern -- a cairo:pattern-t instance
x1 -- a number for the x coordinate of the first control point
y1 -- a number for the y coordinate of the first control point
x2 -- a number for the x coordinate of the second control point
y2 -- a number for the y coordinate of the second control point
x3 -- a number for the x coordinate of the end of the curve
y3 -- a number for the y coordinate of the end of the curve
Details:
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 the cairo:mesh-pattern-curve-to function, this function will behave as if preceded by a call
(cairo:mesh-pattern-move-to pattern x1 y1)  
After this call the current point will be (x3,y3).
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a :invalid-mesh-construction value.
Lisp Implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-19
Function cairo:mesh-pattern-control-point (pattern index point)
Arguments:
pattern -- a cairo:pattern-t instance
index -- an unsigned integer for the patch number to return data for
point -- an unsigned integer for the control point number to return data for
Returns:
x -- a double float with the x coordinate of the control point
y -- a double float with the y coordinate of the control point
Details:
Gets the control point point of patch index for a mesh pattern. Returns nil if index or point is not valid for pattern.

The index argument can range 0 to 1 less than the number returned by the cairo:mesh-pattern-patch-count function.

Valid values for point are from 0 to 3 and identify the control points as explained for the cairo:pattern-create-mesh function.
See also:
2025-1-19
Function cairo:mesh-pattern-set-control-point (pattern point x y)
Arguments:
pattern -- a cairo:pattern-t instance
point -- an unsigned integer for the control point to set the position for
x -- a number coerced to a double float for the x coordinate of the control point
y -- a number coerced to a double float for the y coordinate of the control point
Details:
Set an internal control point of the current patch. Valid values for point are from 0 to 3 and identify the control points as explained for the cairo:pattern-create-mesh function.
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a status of :pattern-type-mismatch. If point is not valid, pattern will be put into an error status with a status of :invalid-index. If pattern has no current patch, pattern will be put into an error status with a status of :invalid-mesh-construction.
See also:
2025-1-19
Function cairo:mesh-pattern-corner-color-rgba (pattern index corner)
Arguments:
pattern -- a cairo:pattern-t instance
index -- an unsigned integer for the patch number to return data for
corner -- an unsigned integer for the corner number to return data for
Returns:
red -- a number with the red component of the color
green -- a number with the green component of the color
blue -- a number with the blue component of the color
alpha -- a number with the alpha component of the color
Details:
Gets the color information in corner corner of patch index for a mesh pattern. Returns nil if pattern or index and corner are not valid for pattern.

The index argument can range 0 to 1 less than the number returned by the cairo:mesh-pattern-patch-count function.

Valid values for corner are from 0 to 3 and identify the corners as explained for the cairo:pattern-create-mesh function.
Notes:
The numbers returned are double floats.
See also:
2025-1-19
Function cairo:mesh-pattern-set-corner-color-rgb (pattern index red green blue)
Arguments:
pattern -- a cairo:pattern-t instance
corner -- an unsigned integer for the corner to set the color for
red -- a number coerced to a double float for the red component of the color
green -- a number coerced to a double float for the green component of the color
blue -- a number coerced to a double float for the blue component of the color
Details:
Sets the color of a corner of the current patch in a mesh pattern. The color is specified in the same way as for the cairo:set-source-rgb function.

Valid values for corner are from 0 to 3 and identify the corners as explained for the cairo:pattern-create-mesh function.
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If corner is not valid, pattern will be put into an error status with a :invalid-index value. If pattern has no current patch, pattern will be put into an error status with a :invalid-mesh-construction value.
See also:
2025-1-19
Function cairo:mesh-pattern-set-corner-color-rgba (pattern index red green blue alpha)
Arguments:
pattern -- a cairo:pattern-t instance
corner -- an unsigned integer for the corner to set the color for
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
Sets the color of a corner of the current patch in a mesh pattern. The color is specified in the same way as for the cairo:set-source-rgba function.

Valid values for corner are from 0 to 3 and identify the corners as explained for the cairo:pattern-create-mesh function.
Notes:
If the pattern argument is not a mesh pattern then pattern will be put into an error status with a :pattern-type-mismatch value. If corner is not valid, pattern will be put into an error status with a :invalid-index value. If pattern has no current patch, pattern will be put into an error status with a :invalid-mesh-construction value.
Lisp implementation:
The arguments are coerced to double floats before being passed to the foreign C function.
See also:
2025-1-19
Function cairo:mesh-pattern-patch-count (pattern)
Arguments:
pattern -- a cairo:pattern-t instance
Returns:
The unsigned integer with the number of patches.
Details:
Gets the number of patches specified in the given mesh pattern. Returns nil if the pattern argument is not a mesh pattern.

The number only includes patches which have been finished by calling the cairo:mesh-pattern-end-patch function. For example it will be 0 during the definition of the first patch.
See also:
2025-1-19
Function cairo:mesh-pattern-path (pattern index)
Arguments:
pattern -- a cairo:pattern-t instance
index -- an unsigned integer for the patch number to return data for
Returns:
The path defining the patch as a list.
Details:
Gets the path defining the patch patch-num for a mesh pattern. Returns nil if the pattern argument is not a mesh pattern or index is not valid for pattern.

The index argument can range 0 to 1 less than the number returned by the cairo:mesh-pattern-patch-count function.
See also:
2025-1-19

Indroduction to Regions

Regions are a simple graphical data type representing an area of integer aligned rectangles. They are often used on raster surfaces to track areas of interest, such as change or clip areas.

Types and functions for Regions

Enum cairo:region-overlap-t
Declaration:
(cffi:defcenum region-overlap-t
  :in
  :out
  :part)  
Values:
:in
The contents are entirely inside the region.
:out
The contents are entirely outside the region.
:part
The contents are partially inside and partially outside the region.
Details:
Used as the return value for the cairo:region-contains-rectangle function.
See also:
2025-1-26
CStruct cairo:region-t
Returned by:
Details:
The cairo:region-t structure represents a set of integer aligned rectangles. It allows operations like the cairo:region-union and cairo:region-intersect functions to be performed on them.

Memory management of the cairo:region-t structure is done with the cairo:region-reference and cairo:region-destroy functions.
See also:
2025-1-26
Function cairo:region-create ()
Returns:
The newly allocated cairo:region-t instance.
Details:
Allocates a new empty region instance. Free with the cairo:region-destroy function. This function always returns a valid instance. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:region-status function.
See also:
2025-1-26
Function cairo:region-create-rectangle (x y width height)
Arguments:
x -- an integer for the x coordinate of the left side of the rectangle
y -- an integer for the y coordinate of the top side of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The newly allocated cairo:region-t instance.
Details:
Allocates a new cairo:region-t instance containing the given rectangle. Free with the cairo:region-destroy function. This function always returns a valid instance. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:region-status function.
Examples:
(defvar rect (cairo:region-create-rectangle 10 20 100 200))
=> RECT
(cairo:region-status rect)
=> :SUCCESS
(cairo:region-extents rect)
=> (10 20 100 200)    
See also:
2025-1-26
Function cairo:region-create-rectangles (&rest rects)
Arguments:
rects -- rectangles, each rectangle is represented as a (x y width height) list with the values for the rectangle
Returns:
The newly allocated cairo:region-t instance.
Details:
Allocates a new cairo:region-t instance containing the union of all given rectangles. Free with the cairo:region-destroy function. This function always returns a valid instance. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:region-status function.
Examples:
(defvar rect (cairo:region-create-rectangles '(0 0 10 20) '(10 20 50 60)))
=> RECT
(cairo:region-status rect)
=> :SUCCESS
(cairo:region-extents rect)
=> (0 0 60 80)    
See also:
2025-1-26
Function cairo:region-copy (region)
Arguments:
region -- a cairo:region-t instance
Returns:
The newly allocated cairo:region-t instance.
Details:
Allocates a new region instance copying the area from region. Free with the cairo:region-destroy function. This function always returns a valid instance. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:region-status function.
See also:
2025-1-26
Function cairo:region-reference (region)
Arguments:
region -- a cairo:region-t instance
Returns:
The referenced cairo:region-t instance.
Details:
Increases the reference count on region by one. This prevents region from being destroyed until a matching call to the cairo:region-destroy function is made.
See also:
2025-1-26
Function cairo:region-destroy (region)
Arguments:
region -- a cairo:region-t instance
Details:
Destroys a cairo:region-t instance.
See also:
2025-1-26
Function cairo:region-status (region)
Arguments:
region -- a cairo:region-t instance
Returns:
The cairo:status-t value that is :success or :no-memory.
Details:
Checks whether an error has previous occurred for this region instance.
See also:
2025-1-26
Function cairo:region-extents (region)
Syntax:
(cairo:region-extents region) => (list x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate of the left side of the rectangle
y -- an integer for the y coordinate of the top side of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The (x y width height) list with the coordinates of the bounding rectangle.
Details:
Gets the bounding rectangle of region as a list of the coordinates.
See also:
2025-1-26
Function cairo:region-num-rectangles (region)
Arguments:
region -- a cairo:region-t instance
Returns:
The integer with the number of rectangles contained in region.
Details:
Returns the number of rectangles contained in region.
See also:
2025-1-26
Function cairo:region-rectangle (region nth)
Syntax:
(cairo:region-rectangle region nth) => (list x y width height)
Arguments:
region -- a cairo:region-t instance
nth -- an integer indicating which rectangle should be returned
x -- an integer for the x coordinate of the left side of the rectangle
y -- an integer for the y coordinate of the top side of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The (x y width height) list with the coordinates of the nth rectangle.
Details:
Returns the nth rectangle from the region as a list with the coordinates of the rectangle.
See also:
2025-1-26
Function cairo:region-is-empty (region)
Arguments:
region -- a cairo:region-t instance
Returns:
True if region is empty, false if it is not.
Details:
Checks whether region is empty.
See also:
2025-1-26
Function cairo:region-contains-point (region x y)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate of a point
y -- an integer for the y coordinate of a point
Returns:
True if (x,y) is contained in region, false if it is not.
Details:
Checks whether (x,y) is contained in region.
See also:
2025-1-26
Function cairo:region-contains-rectangle (region x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate of the left side of the rectangle
y -- an integer for the y coordinate of the top side of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
Details:
Checks whether the given rectangle is inside, outside or partially contained in region. Returns the :in value if rectangle is entirely inside region, the :out value if rectangle is entirely outside region, or the :part value if rectangle is partially inside and partially outside region.
See also:
2025-1-26
Function cairo:region-equal (region1 region2)
Arguments:
region1 -- a cairo:region-t instance
region2 -- a cairo:region-t instance
Returns:
True if both regions contained the same coverage, false if it is not or any region is in an error status.
Details:
Compares whether region1 is equivalent to region2.
See also:
2025-1-26
Function cairo:region-translate (region dx dy)
Arguments:
region -- a cairo:region-t instance
dx -- an integer for the amount to translate in the x direction
dy -- an integer for the amount to translate in the y direction
Details:
Translates the region by (dx, dy).
See also:
2025-1-26
Function cairo:region-intersect (region other)
Arguments:
region -- a cairo:region-t instance
other -- another cairo:region-t instance
Returns:
The passed in cairo:region-t instance with the intersection or nil if an error occured.
Details:
Computes the intersection of region with other and places the result in region.
See also:
2025-1-26
Function cairo:region-intersect-rectangle (region x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate with the left side of the rectangle
y -- an integer for the y coordinate with the top side of the rectangle
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The passed in cairo:region-t instance with the intersection or nil if an error occured.
Details:
Computes the intersection of region with the given rectangle and places the result in region.
See also:
2025-1-26
Function cairo:region-subtract (region other)
Arguments:
region -- a cairo:region-t instance
other -- another cairo:region-t instance
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Subtracts other from region and places the result in region.
See also:
2025-1-26
Function cairo:region-subtract-rectangle (region x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate
y -- an integer for the y coordinate
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Subtracts rectangle from region and places the result in region.
See also:
2025-1-26
Function cairo:region-union (region other)
Arguments:
region -- a cairo:region-t instance
other -- another cairo:region-t instance
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Computes the union of region with other and places the result in region.
See also:
2025-1-26
Function cairo:region-union-rectangle (region x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate
y -- an integer for the y coordinate
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Computes the union of region with rectangle and places the result in region.
See also:
2025-1-26
Function cairo:region-xor (region other)
Arguments:
region -- a cairo:region-t instance
other -- another cairo:region-t instance
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Computes the exclusive difference of region with other and places the result in region. That is, region will be set to contain all areas that are either in region or in other, but not in both.
See also:
2025-1-26
Function cairo:region-xor-rectangle (region x y width height)
Arguments:
region -- a cairo:region-t instance
x -- an integer for the x coordinate
y -- an integer for the y coordinate
width -- an integer for the width of the rectangle
height -- an integer for the height of the rectangle
Returns:
The passed in cairo:region-t instance with the result or nil if an error occured.
Details:
Computes the exclusive difference of region with rectangle and places the result in region. That is, region will be set to contain all areas that are either in region or in rectangle, but not in both.
See also:
cairo:region-t
cairo:rectangle-int-t
2025-1-26

Introduction to Transformations

The current transformation matrix, CTM, is a two-dimensional affine transformation that maps all coordinates and other drawing instruments from the user space into the surface's canonical coordinate system, also known as the device space.

Functions for Transformations

Function cairo:translate (cr tx ty)
Arguments:
cr -- a cairo:context-t instance
tx -- a number coerced to a double float for the amount to translate in the x direction
ty -- a number coerced to a double float for the amount to translate in the y direction
Details:
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 the cairo:translate function. In other words, the translation of the user-space origin takes place after any existing transformation.
See also:
2025-1-29
Function cairo:scale (cr sx sy)
Arguments:
cr -- a cairo:context-t instance
sx -- a number coerced to a double float for the scale factor for the x dimension
sy -- a number coerced to a double float for the scale factor for the y dimension
Details:
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.
See also:
2025-1-29
Function cairo:rotate (cr angle)
Arguments:
cr -- a cairo:context-t instance
angle -- a number coerced to a double float for an angle in radians by which the user-space axes will be rotated
Details:
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.
See also:
2025-1-29
Function cairo:transform (cr matrix)
Arguments:
cr -- a cairo:context-t instance
matrix -- a cairo:matrix-t instance for the transformation to be applied to the user-space axes
Details:
Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.
See also:
2025-1-29
Function cairo:matrix (cr matrix)
Syntax:
(cairo:matrix cr matrix) => matrix
(setf (cairo:matrix cr) matrix)
Arguments:
cr -- a cairo:context-t instance
matrix -- a cairo:matrix-t transformation matrix from user space to device space
Details:
The cairo:matrix function gets the current transformation matrix (CTM). The (setf cairo:matrix) function modifies the current transformation matrix (CTM) by setting it equal to matrix.
Notes:
The cairo:matrix-t structure is a foreign CFFI structure, therefore we pass in a valid cairo:matrix-t instance to the cairo:matrix function which is filled with the current transformation matrix.
See also:
2025-1-29
Function cairo:identity-matrix (cr)
Arguments:
cr -- a cairo:context-t instance
Details:
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.
See also:
2025-1-29
Function cairo:user-to-device (cr x y)
Arguments:
cr -- a cairo:context-t instance
Returns:
x -- a double float with the x value of the coordinate
y -- a double float with the y value of the coordinate
Details:
Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
See also:
2025-1-29
Function cairo:user-to-device-distance (cr dx dy)
Arguments:
cr -- a cairo:context-t instance
Returns:
dx -- a double float with the x component of a distance vector
dy -- a double float with the y component of a distance vector
Details:
Transform a distance vector from user space to device space. This function is similar to the cairo:user-to-device function except that the translation components of the CTM will be ignored when transforming (dx,dy).
See also:
2025-1-29
Function cairo:device-to-user (cr x y)
Arguments:
cr -- a cairo:context-t instance
Returns:
x -- a double float with the x value of the coordinate
y -- a double float with the y value of the coordinate
Details:
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).
See also:
2025-1-29
Function cairo:device-to-user-distance (cr dx dy)
Arguments:
cr -- a cairo:context-t instance
Returns:
dx -- a double float with the x component of the distance vector
dy -- a double float with the y component of the distance vector
Details:
Transform a distance vector from device space to user space. This function is similar to the cairo:device-to-user function except that the translation components of the inverse CTM will be ignored when transforming (dx,dy).
See also:
2025-1-29

Introduction to Text

The functions with text in their name form Cairo's toy text API. The toy API takes UTF-8 encoded text and is limited in its functionality to rendering simple left-to-right text with no advanced features. That means for example that most complex scripts like Hebrew, Arabic, and Indic scripts are out of question. No kerning or correct positioning of diacritical marks either. The font selection is pretty limited too and does not handle the case that the selected font does not cover the characters in the text. This set of functions are really that, a toy text API, for testing and demonstration purposes. Any serious application should avoid them.

The functions with glyphs in their name form Cairo's low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo library that is part of the Pango text layout and rendering library. Pango is available from the Pango library.

Types and functions for Text

CEnum cairo:font-slant-t
Declaration:
(cffi:defcenum font-slant-t
  :normal
  :italic
  :oblique)  
Values:
:normal
Upright font style.
:italic
Italic font style.
:oblique
Oblique font style.
Details:
Specifies variants of a font face based on their slant.
See also:
2025-1-29
CEnum cairo:font-weight-t
Declaration:
(cffi:defcenum font-slant-t
  :normal
  :bold)  
Values:
:normal
Normal font weight.
:bold
Bold font weight.
Details:
Specifies variants of a font face based on their weight.
See also:
2025-1-29
CStruct cairo:glyph-t
Declaration:
(cffi:defcstruct glyph-t
  (index :ulong)
  (x :double)
  (y :double))  
Values:
index
Glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
x
The offset in the x direction between the origin used for drawing or measuring the string and the origin of this glyph.
y
The offset in the y direction between the origin used for drawing or measuring the string and the origin of this glyph.
Details:
The cairo:glyph-t structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo does not expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.

Note that the offsets given by x and y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin.
Notes:
In the Lisp API, this structure is only used to implement functions that work with glyphs and accept or return a glyph or an array of glyphs. In the Lisp implementation a glyph is represented as a list:
(list index x y)    
An array of glyphs is represented as a list:
(list (list index1 x1 y1) (list index2 x2 y2) ... )    
See also:
2025-1-29
Function cairo:select-font-face (cr family &key slant weight)
Arguments:
cr -- a cairo:context-t instance
family -- a string for the font family name, encoded in UTF-8
slant -- a cairo:font-slant-t value for the slant, default value is :normal
weight -- a cairo:font-weight-t value for the weight, default value is :normal
Details:
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.

If text is drawn without a call to the cairo:select-font-face function, nor the cairo:font-face function nor the cairo:scaled-font function, the default family is platform-specific, but is essentially "sans-serif". Default slant is :normal, and default weight is :normal.

This function is equivalent to a call to the cairo:toy-font-face-create function followed by the cairo:font-face function.
Notes:
The cairo:select-font-face function 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. 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.
See also:
2025-1-29
Function cairo:set-font-size (cr size)
Arguments:
cr -- a cairo:context-t instance
size -- a number coerced to a double float for the new font size, in user space units
Details:
Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with the cairo:set-font-size or cairo:font-matrix functions. This results in a font size of size user space units. More precisely, this matrix will result in the em-square of the font being a size by size square in user space.

If text is drawn without a call to the cairo:set-font-size function, nor the cairo:font-matrix or cairo:scaled-font-t functions, the default font size is 10.0.
See also:
2025-1-29
Function cairo:font-matrix (cr matrix)
Syntax:
(cairo:font-matrix cr matrix) => matrix
(setf (cairo:font-matrix cr) matrix)
Arguments:
cr -- a cairo:context-t instance
matrix -- a cairo:matrix-t instance for the values of the matrix
Details:
The cairo:font-matrix function stores the current font matrix into matrix and returns the cairo:matrix-t instance. The (setf cairo:font-matrix) function sets the current font matrix.

The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used, see the cairo:set-font-size function, but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes.
See also:
2025-1-29
Function cairo:font-options (cr options)
Syntax:
(cairo:font-options cr options) => options
(setf (cairo:font-options cr) options)
Arguments:
cr -- a cairo:context-t instance
options -- a cairo:font-options-t instance
Details:
The cairo:font-options function retrieves font rendering options for the Cairo context. The (setf cairo:font-options) function sets a set of custom font rendering options.

Note that the returned font options do not include any font options derived from the underlying surface. They are literally the font options passed to the (setf cairo:font-options) function.

Rendering font options are derived by merging options with the options derived from underlying surface. If the value in options has a default value, like :default, then the value from the surface is used.
See also:
2025-1-29
Function cairo:font-face (cr)
Syntax:
(cairo:font-face cr) => face
(setf (cairo:font-face cr) face)
Arguments:
cr -- a cairo:context-t instance
face -- a cairo:font-face-t instance, or nil to restore to the default font
Details:
The cairo:font-face function gets the current font face for a Cairo context. The (setf cairo:font-face) function replaces the current font face. The replaced font face in the Cairo context will be destroyed if there are no other references to it.

This object is owned by Cairo. To keep a reference to it, you must call the cairo:font-face-reference function. This function always returns a cairo:font-face-t instance. If memory cannot be allocated, a special "nil" instance will be returned on which the cairo:font-face-status function returns the :no-memory value. Using this "nil" instance will cause its error state to propagate to other objects it is passed to, for example, calling the cairo:font-face function with a "nil" font will trigger an error that will shutdown the Cairo context.
See also:
2025-1-29
Function cairo:scaled-font (cr)
Syntax:
(cairo:scaled-font cr) => font
(setf (cairo:scaled-font cr) font)
Arguments:
cr -- a cairo:context-t instance
font -- a cairo:scaled-font-t instance
Details:
The cairo:scaled-font function gets the current scaled font for the Cairo context. The (setf cairo:scaled-font) function replaces the current font face, font matrix, and font options in the Cairo context.

Except for some translation, the current transformation matrix CTM of the Cairo context should be the same as that of the cairo:scaled-font-t instance, which can be accessed using the cairo:scaled-font-ctm function.

This object is owned by Cairo. To keep a reference to it, you must call the cairo:scaled-font-reference function. This function always returns a cairo:scaled-font-t instance. If memory cannot be allocated, a special "nil" instance will be returned on which the cairo:scaled-font-status function returns the :no-memory value. Using this "nil" instance will cause its error state to propagate to other objects it is passed to, for example, calling the cairo:scaled-font function with a "nil" font will trigger an error that will shutdown the Cairo context.
See also:
2025-1-29
Function cairo:show-text (cr utf8)
Arguments:
cr -- a cairo:context-t instance
utf8 -- a string of text encoded in UTF-8, or nil
Details:
A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current font face, font size (font matrix), 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 the cairo:show-text function.
Notes:
The cairo:show-text function 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 the cairo:show-glyphs function for the "real" text display API in Cairo.
See also:
2025-1-29
Function cairo:show-glyphs (cr glyphs)
Arguments:
cr -- a cairo:context-t instance
glyphs -- a list of glyphs to show, each glyph is represented by an item that is a list for the (index x y) glyph values
index -- an unsigned integer for the glyph index in the font
x -- a number coerced to a double float for the offset in the x direction between the origin used for drawing the string and the orgin of this glyph
y -- a number coerced to a double float for the y direction between the orgin used for drawing the string and the origin of this glyph
Details:
A drawing operator that generates the shape from a list of glyphs, rendered according to the current font face, font size (font matrix), and font options.
See also:
2025-1-29
Function cairo:font-extents (cr)
Syntax:
(cairo:font-extents cr) => ascent, descent, height, max-xadvance, max-yadvance
Arguments:
cr -- a cairo:context-t instance
Returns:
The double floats of the cairo:font-extents-t instance.
Details:
Gets the font extents for the currently selected font.
See also:
2025-1-29
Function cairo:text-extents (cr utf8)
Syntax:
(cairo:text-extents cr utf8) => xbearing, ybearing, width, height xadvance, yadvance
Arguments:
cr -- a cairo:context-t instance
utf8 -- a string of text encoded in UTF-8
Returns:
The double floats of the cairo:text-extents-t instance for the extents of utf8.
Details:
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 the cairo:show-text function. Additionally, the xadvance and yadvance values indicate the amount by which the current point would be advanced by the cairo:show-text function.

Note that whitespace characters do not directly contribute to the size of the rectangle width and height values. 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 xadvance and yadvance values.
See also:
2025-1-29
Function cairo:glyph-extents (cr glyphs)
Syntax:
(cairo:glyph-extents cr glyphs) => xbearing, ybearing, width, height, xadvance, yadvance
Arguments:
cr -- a cairo:context-t instance
glyphs -- a list of glyphs, each glyph is represented by an item that is a list for the (index x y) glyph values
index -- an unsigned integer for the glyph index in the font
x -- a number coerced to a double float for the offset in the x direction between the origin used for drawing the string and the orgin of this glyph
y -- a number coerced to a double float for the y direction between the orgin used for drawing the string and the origin of this glyph
Returns:
The double floats of the cairo:text-extents-t instance for the extents of glyphs.
Details:
Gets the extents for a list of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, as they would be drawn by the cairo:show-glyphs function. Additionally, the xadvance and yadvance values indicate the amount by which the current point would be advanced by the cairo:show-glyphs function.

Note that whitespace glyphs do not contribute to the size of the rectangle width and height values.
See also:
2025-1-29
Macro cairo:with-toy-font-face ((face &rest args) &body body)
Syntax:
(cairo:with-toy-font-face (face family slant weight) body) => result
Arguments:
face -- a newly allocated cairo:font-face-t instance
familiy -- a string for the font family name, encoded in UTF-8
slant -- a cairo:font-slant-t value for the slant for the font
weight -- a cairo:font-weight-t value for the weight for the font
Details:
The cairo:with-toy-font-face macro allocates a new cairo:font-face-t instance and executes the body that uses the toy font face. After execution of the body the allocated memory for the font face is released. See the cairo:toy-font-face-create function for more information.
See also:
2025-1-29
Function cairo:toy-font-face-create (family slant weight)
Arguments:
familiy -- a string for the font family name, encoded in UTF-8
slant -- a cairo:font-slant-t slant for the font
weight -- a cairo:font-weight-t weight for the font
Returns:
The newly created cairo:font-face-t instance. Free with the cairo:font-face-destroy function when you are done using it.
Details:
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 the cairo:toy-font-face-family function.

The cairo:select-font-face function uses this to create font faces. See that function for limitations and other details of toy font faces.
See also:
2025-1-29
Function cairo:toy-font-face-family (face)
Arguments:
face -- a cairo:font-face-t instance
Returns:
The string with the family name.
Details:
Gets the family name of a toy font face.
See also:
2025-1-29
Function cairo:toy-font-face-slant (face)
Arguments:
face -- a cairo:font-face-t instance
Returns:
The cairo:font-slant-t slant value.
Details:
Gets the slant of a toy font face.
See also:
2025-1-29
Function cairo:toy-font-face-weight (face)
Arguments:
face -- a cairo:font-face-t instance
Returns:
The cairo:font-weight-t weight value.
Details:
Gets the weight of a toy font face.
See also:
2025-1-29

Fonts

Indroduction to Font Faces

Base class for font faces. The cairo:font-face-t structure 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 cairo:backend-font-face-create, or implicitly using the toy text API by way of the cairo:select-font-face function. The resulting face can be accessed using the cairo:font-face function.

Type and functions for Font Faces

CEnum cairo:font-type-t
Declaration:
(cffi:defcenum font-type-t
  :toy
  :ft
  :win32
  :quartz
  :user
  :dwrite)  
Values:
:toy
The font was created using Cairo's toy font API.
:ft
The font is of type FreeType.
:win32
The font is of type Win32.
:quartz
The font is of type Quartz.
:user
The font was created using Cairo's user font API.
:dwrite
The font is of type Win32 DWrite. Since 1.18
Details:
The cairo:font-type-t enumeration 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 type-font-face-create. The font face type can be queried with the cairo:font-face-type function.

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 the cairo:scaled-font-create function. The scaled font type can be queried with the cairo:scaled-font-type function.

The various cairo:scaled-font-t 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 type-scaled-font such as the cairo:ft-scaled-font-lock-face function.

The behavior of calling a type-specific function with a scaled font of the wrong type is undefined.
See also:
2025-1-29
CStruct cairo:font-face-t
Details:
The cairo:font-face-t structure specifies all aspects of a font other than the size or font matrix. A font matrix is used to distort a font by sheering it or scaling it unequally in the two directions. A font face can be set on a Cairo context by using the cairo:font-face function. The size and font matrix are set with the cairo:set-font-size and cairo:font-matrix functions.

There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using the cairo:font-face-type function.

Memory management of the cairo:font-face-t structure is done with the cairo:font-face-reference and cairo:font-face-destroy functions. cairo:font-face
See also:
2025-1-29
Function cairo:font-face-reference (face)
Arguments:
face -- a cairo:font-face-t instance, may be nil in which case this function does nothing
Returns:
The referenced cairo:font-face-t instance.
Details:
Increases the reference count on face by one. This prevents the font face from being destroyed until a matching call to the cairo:font-face-destroy function is made.

The number of references to a cairo:font-face-t instance can be get using the cairo:font-face-reference-count function.
See also:
2025-1-29
Function cairo:font-face-reference-count (face)
Arguments:
face -- a cairo:font-face-t instance
Returns:
The unsigned integer with the current reference count of face. If the object is a "nil" object, 0 will be returned.
Details:
Returns the current reference count of the font face.
See also:
2025-1-29
Function cairo:font-face-destroy (face)
Arguments:
face -- a cairo:font-face-t instance
Details:
Decreases the reference count on face by one. If the result is zero, then face and all associated resources are freed. See the cairo:font-face-reference function.
See also:
2025-1-29
Function cairo:font-face-status (face)
Arguments:
face -- a cairo:font-face-t instance
Returns:
The :success value of the cairo:status-t enumeration or another error such as the :no-memory value.
Details:
Checks whether an error has previously occurred for this font face.
See also:
2025-1-29
Function cairo:font-face-type (face)
Arguments:
face -- a cairo:font-face-t font face
Returns:
The cairo:font-type-t value with the type of face.
Details:
This function returns the type of the backend used to create a font face. See the cairo:font-type-t enumeration for available types.
See also:
2025-1-29

Indroduction to Scaled Fonts

The cairo:scaled-font-t structure represents a realization of a font face at a particular size and transformation and a certain set of font options.

Types and functions for Scaled Fonts

CStruct cairo:font-extents-t
Declaration:
(cffi:defcstruct font-extents-t
  (ascent :double)
  (descent :double)
  (height :double)
  (max-xadvance :double)
  (max-yadvance :double))  
Values:
ascent
The distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
descent
The distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements below it.
height
The recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent + descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent + descent between lines.
max-xadvance
The maximum distance in the x direction that the origin is advanced for any glyph in the font.
max-yadvance
The maximum distance in the y direction that the origin is advanced for any glyph in the font. This will be zero for normal fonts used for horizontal writing. The scripts of East Asia are sometimes written vertically.
Details:
The cairo:font-extents-t structure stores metric information for a font. Values are given in the current user-space coordinate system. Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call (cairo:scale cr 2.0 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting, so you can not assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.
See also:
2025-1-29
CStruct cairo:text-extents-t
Declaration:
(cffi:defcstruct text-extents-t
  (xbearing :double)
  (ybearing :double)
  (width :double)
  (height :double)
  (xadvance :double)
  (yadvance :double))  
Values:
xbearing
The horizontal distance from the origin to the leftmost part of the glyphs as drawn. Positive if the glyphs lie entirely to the right of the origin.
ybearing
The vertical distance from the origin to the topmost part of the glyphs as drawn. Positive only if the glyphs lie completely below the origin; will usually be negative.
width
Width of the glyphs as drawn.
height
Height of the glyphs as drawn.
xadvance
Distance to advance in the x direction after drawing these glyphs.
yadvance
Distance to advance in the y direction after drawing these glyphs. Will typically be zero except for vertical text layout as found in East-Asian languages.
Details:
The cairo:text-extents-t structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call (scale cr 2.0 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting, so you can not assume that metrics are independent of the transformation matrix, but otherwise will remain unchanged.
See also:
2025-1-29
CStruct cairo:scaled-font-t
Details:
The cairo:scaled-font-t structure is a font scaled to a particular size and device resolution. The cairo:scaled-font-t structure is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.

There are various types of scaled fonts, depending on the font backend they use. The type of a scaled font can be queried using the cairo:scaled-font-type function.

Memory management of the cairo:scaled-font-t structure is done with the cairo:scaled-font-reference and cairo:scaled-font-destroy functions.
See also:
2025-1-29
Macro cairo:with-scaled-font ((font face matrix ctm options) &body body)
Syntax:
(cairo:with-scaled-font (font face matrix ctm options) body) => result
Arguments:
font -- a newly allocated cairo:scaled-font-t instance
matrix -- a cairo:matrix-t matrix for the font space to user space transformation for the font, in the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes, see the cairo:font-matrix function
ctm -- a cairo:matrix-t matrix for the user to device transformation with which the font will be used
options -- a cairo:font-options-t value for the options to use when getting metrics for the font and rendering with it
Details:
The cairo:with-scaled-font macro allocates a new cairo:scaled-font-t instance for the given arguments and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo scaled font is released.

This macro allocates the Cairo scaled font with the cairo:scaled-font-create function and destroys it with the cairo:scaled-font-destroy function.
See also:
2025-1-29
Function cairo:scaled-font-create (face matrix ctm options)
Arguments:
face -- a cairo:font-face-t instance
matrix -- a cairo:matrix-t matrix for the font space to user space transformation for the font, in the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes, see the cairo:font-matrix function
ctm -- a cairo:matrix-t matrix for the user to device transformation with which the font will be used
options -- a cairo:font-options-t value for the options to use when getting metrics for the font and rendering with it
Returns:
The newly created cairo:scaled-font-t instance. Destroy with the cairo:scaled-font-destroy function.
Details:
Creates a cairo:scaled-font-t instance from a font face and matrices that describe the size of the font and the environment in which it will be used.
See also:
2025-1-29
Function cairo:scaled-font-reference (font)
Arguments:
font -- a cairo:scaled-font-t instance, may be nil in which case this function does nothing
Returns:
The referenced cairo:scaled-font-t instance.
Details:
Increases the reference count on font by one. This prevents font from being destroyed until a matching call to the cairo:scaled-font-destroy function is made. The number of references to a cairo:scaled-font-t instance can be get using the cairo:scaled-font-reference-count function.
See also:
2025-1-29
Function cairo:scaled-font-reference-count (font)
Arguments:
font -- a cairo:scaled-font-t instance
Returns:
The unsigned integer with the current reference count of font. If the object is a "nil" object, 0 will be returned.
Details:
Returns the current reference count of font.
See also:
2025-1-29
Function cairo:scaled-font-destroy (font)
Arguments:
font -- a cairo:scaled-font-t instance
Details:
Decreases the reference count on font by one. If the result is zero, then font and all associated resources are freed. See the cairo:scaled-font-reference function.
See also:
2025-1-29
Function cairo:scaled-font-status (font)
Arguments:
font -- a cairo:scaled-font-t instance
Returns:
The :success value of the cairo:status-t enumeration or another error such as :no-memory.
Details:
Checks whether an error has previously occurred for this scaled font.
See also:
2025-1-29
Function cairo:scaled-font-type (font)
Arguments:
font -- a cairo:scaled-font-t instance
Returns:
The cairo:font-type-t value of font.
Details:
This function returns the type of the backend used to create a scaled font. See the cairo:font-type-t enumeration for available types. However, this function never returns the :toy value.
See also:
2025-1-29
Function cairo:scaled-font-font-face (font)
Arguments:
font -- a cairo:scaled-font-t instance
Returns:
The cairo:font-face-t instance with which font was created. This object is owned by Cairo. To keep a reference to it, you must call the cairo:scaled-font-reference function.
Details:
Gets the font face that this scaled font uses. This might be the font face passed to the cairo:scaled-font-create function, but this does not hold true for all possible cases.
See also:
2025-1-29
Function cairo:scaled-font-font-options (font options)
Arguments:
font -- a cairo:scaled-font-t instance
options -- a cairo:font-options-t instance for the return value
Returns:
The cairo:font-options-t instance with the font options.
Details:
Stores the font options with which font was created into options.
See also:
2025-1-29
Function cairo:scaled-font-font-matrix (font matrix)
Arguments:
font -- a cairo:scaled-font-t instance
matrix -- a cairo:matrix-t instance
Returns:
The cairo:matrix-t instance with the font matrix.
Details:
Stores the font matrix with which font was created into matrix.
See also:
2025-1-29
Function cairo:scaled-font-ctm (font ctm)
Arguments:
font -- a cairo:scaled-font-t instance
ctm -- a cairo:matrix-t instance for the return value for the CTM
Returns:
The cairo:matrix-t instance with the CTM.
Details:
Stores the CTM with which font was created into ctm. Note that the translation offsets (x0,y0) of the CTM are ignored by the cairo:scaled-font-create function. So, the matrix this function returns always has (0,0) as (x0,y0).
See also:
2025-1-29
Function cairo:scaled-font-scale-matrix (font matrix)
Arguments:
font -- a cairo:scaled-font-t instance
matrix -- a cairo:matrix-t instance for the scale matrix
Returns:
The cairo:matrix-t instance with the scale matrix.
Details:
Stores the scale matrix of font into matrix. The scale matrix is product of the font matrix and the CTM associated with the scaled font, and hence is the matrix mapping from font space to device space.
See also:
2025-1-29
Function cairo:scaled-font-extents (font)
Syntax:
(cairo:scaled-font-extents font) => ascent, descent, height, max-xadvance, max-yadvance
Arguments:
font -- a cairo:scaled-font-t instance
Returns:
The double floats of the cairo:font-extents-t instance with the extents of font.
Details:
Gets the metrics for a scaled font.
See also:
2025-1-29
Function cairo:scaled-font-text-extents (font utf8)
Syntax:
(cairo:scaled-font-text-extents font utf8) => xbearing, ybearing, width, height, xadvance, yadvance
Arguments:
font -- a cairo:scaled-font-t instance
utf8 -- a string of text, encoded in UTF-8
Returns:
The double floats of the cairo:text-extents-t instance with the extents of utf8.
Details:
Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text drawn at the origin (0,0), as it would be drawn by the cairo:show-text function if the Cairo graphics state were set to the same cairo:font-face, cairo:set-font-matrix, ctm, and cairo:font-options as font. Additionally, the xadvance and yadvance values indicate the amount by which the current point would be advanced by the cairo:show-text function.

Note that whitespace characters do not directly contribute to the size of the rectangle width and height values. 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 xadvance and yadvance values.
See also:
2025-1-29
Function cairo:scaled-font-glyph-extents (font glyphs)
Syntax:
(cairo:scaled-font-glyph-extents font glyphs) => xbearing, ybearing, width, height, xadvance, yadvance
Arguments:
font -- a cairo:scaled-font-t instance
glyphs -- a list of glyphs, each glyph is represented by an item that is a list with the (index x y) glyph values
index -- an unsigned integer for the glyph index in the font
x -- a number coerced to a double float for the offset in the x direction between the origin used for drawing the string and the orgin of this glyph
y -- a number coerced to a double float for the y direction between the orgin used for drawing the string and the origin of this glyph
Returns:
The double floats of the cairo:text-extents-t instance with the extents of glyphs.
Details:
Gets the extents for glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, as they would be drawn by the cairo:show-glyphs function if the Cairo graphics state were set to the same font-face, font-matrix, ctm, and font-options as font. Additionally, the xadvance and yadvance values indicate the amount by which the current point would be advanced by the cairo:show-glyphs function.

Note that whitespace glyphs do not contribute to the size of the rectangle width and height values.
See also:
2025-1-29
Function cairo:scaled-font-text-to-glyphs (font x y utf8)
Arguments:
font -- a cairo:scaled-font-t instance
x -- a number coerced to a double float for the x position to place first glyph
y -- a number coerced to a double float for the y position to place first glyph
utf8 -- a string of text encoded in UTF8
Returns:
The list of glyphs for utf8 upon sucess, or nil if the input values are wrong or if conversion failed. If the input values are correct but the conversion failed, the error status is set on font.
Details:
Converts UTF8 text to a list of glyphs. The output values can be readily passed to the cairo:show-glyphs function, or related functions, assuming that the exact same font is used for the operation.
Lisp implementation:
The C function also enables cluster mapping. Currently, cluster mapping is not implemented for the Lisp API.
See also:
2025-1-29

Introduction to Font 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.

Types and functions for Font Options

CEnum cairo:subpixel-order-t
Declaration:
(cffi:defcenum subpixel-order-t
  :default
  :rgb
  :bgr
  :vrgb
  :vbgr)  
Values:
:default
Use the default subpixel order for the target device.
:rgb
Subpixel elements are arranged horizontally with red at the left.
:bgr
Subpixel elements are arranged horizontally with blue at the left.
:vrgb
Subpixel elements are arranged vertically with red at the top.
:vbgr
Subpixel elements are arranged vertically with blue at the top.
Details:
The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of :subpixel.

See also:
2025-1-29
CEnum cairo:hint-style-t
Declaration:
(cffi:defcenum hint-style-t
  :default
  :none
  :slight
  :medium
  :full)  
Values:
:default
Use the default hint style for font backend and target device.
:none
Do not hint outlines.
:sligth
Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
:medium
Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast.
:full
Hint outlines to maximize contrast.
Details:
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.
See also:
2025-1-29
CEnum cairo:hint-metrics-t
Declaration:
(cffi:defcenum hint-metrics-t
  :default
  :off
  :on)  
Values:
:default
Hint metrics in the default manner for the font backend and target device.
:off
Do not hint font metrics.
:on
Hint font metrics.
Details:
Specifies whether to hint font metrics. Hinting font metrics means quantizing them so that they are integers 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.
See also:
2025-1-29
CEnum cairo:color-mode-t
Declaration:
(cffi:defcenum color-mode-t
  :default
  :no-color
  :color)  
Values:
:default
Use the default color mode for font backend and target device.
:no-color
Disable rendering color glyphs. Glyphs are always rendered as outline glyphs.
:color
Enable rendering color glyphs. If the font contains a color presentation for a glyph, and when supported by the font backend, the glyph will be rendered in color.
Details:
Specifies if color fonts are to be rendered using the color glyphs or outline glyphs. Glyphs that do not have a color presentation, and non-color fonts are not affected by this font option.

Since 1.18
See also:
2025-1-29
CStruct cairo:font-options-t
Details:
The cairo:font-options-t structure is an opaque structure holding all options that are used when rendering fonts. Individual features of a cairo:font-options-t instance can be set or accessed using accessor functions named cairo:font-options-feature-name, like the cairo:font-options-antialias function.

New features may be added to a cairo:font-options-t structure in the future. For this reason, the cairo:font-options-copy, cairo:font-options-equal, cairo:font-options-merge, and cairo:font-options-hash functions should be used to copy, check for equality, merge, or compute a hash value of cairo:font-options-t instances.
See also:
2025-1-29
Function cairo:font-options-create ()
Returns:
The newly allocated cairo:font-options-t instance.
Details:
Allocates a new font options instance with all options initialized to default values. Free with the cairo:font-options-destroy function. This function always returns a valid pointer. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:font-options-status function.
See also:
2025-1-29
Function cairo:font-options-copy (options)
Arguments:
options -- a cairo:font-options-t instance
Returns:
The newly allocated cairo:font-options-t instance.
Details:
Allocates a new font options object copying the option values from original. Free with the cairo:font-options-destroy function. This function always returns a valid pointer. If memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with the cairo:font-options-status function.
See also:
2025-1-29
Function cairo:font-options-destroy (options)
Arguments:
options -- a cairo:font-options-t instance
Details:
Destroys a cairo:font-options-t instance created with the cairo:font-options-create or cairo:font-options-copy function.
See also:
2025-1-29
Function cairo:font-options-status (options)
Arguments:
options -- a cairo:font-options-t instance
Returns:
The :success or :no-memory values of the cairo:status-t enumeration.
Details:
Checks whether an error has previously occurred for this font options instance.
See also:
2025-1-29
Function cairo:font-options-merge (options other)
Arguments:
options -- a cairo:font-options-t instance
other -- another cairo:font-options-t instance
Details:
Merges non-default options from other into options, replacing existing values. This operation can be thought of as somewhat similar to compositing other onto options with the operation of :over.
See also:
2025-1-29
Function cairo:font-options-hash (options)
Arguments:
options -- a cairo:font-options-t instance
Returns:
The unsigned long integer with the hash value for the font options object.
Details:
Compute a hash for the font options instance. This value will be useful when storing an object containing a cairo:font-options-t instance in a hash table.
See also:
2025-1-29
Function cairo:font-options-equal (options other)
Arguments:
options -- a cairo:font-options-t instance
other -- another cairo:font-options-t instance
Returns:
True if all fields of the two font options instances match. Note that this function will return false if either instance is in error.
Details:
Compares two font options instances for equality.
See also:
2025-1-29
Function cairo:font-options-antialias (options)
Syntax:
(cairo:font-options-antialias options) => antialias
(setf (cairo:font-options-antialias options) antialias)
Arguments:
options -- a cairo:font-options-t instance
antialias -- a cairo:antialias-t value
Details:
The cairo:font-options-antialias function gets the antialiasing mode for the font options instance. The (setf cairo:font-options-antialias) function sets the antialiasing mode. This specifies the type of antialiasing to do when rendering text.
See also:
2025-1-29
Function cairo:font-options-subpixel-order (options)
Syntax:
(cairo:font-options-subpixel-order options) => order
(setf (cairo:font-options-subpixel-order options) order)
Arguments:
options -- a cairo:font-options-t instance
order -- a cairo:subpixel-order-t value
Details:
The cairo:font-options-subpixel-order function gets the subpixel order for the font options instance. The (setf cairo:font-options-subpixel-order) function sets the subpixel order. The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of :subpixel. See the documentation for the cairo:subpixel-order-t enumeration for full details.
See also:
2025-1-29
Function cairo:font-options-hint-style (options)
Syntax:
(cairo:font-options-hint-style options) => style
(setf (cairo:font-options-hint-style options) style)
Arguments:
options -- a cairo:font-options-t instance
style -- a cairo:hint-style-t value
Details:
The cairo:font-options-hint-style function gets the hint style for font outlines for the font options instance. The (setf cairo:font-options-hint-style) function sets the hint style for font outlines for the font options instance. 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 the cairo:hint-style-t enumeration for full details.
See also:
2025-1-29
Function cairo:font-options-hint-metrics (options)
Syntax:
(cairo:font-options-hint-metrics options) => metrics
(setf (cairo:font-options-hint-metrics options) metrics)
Arguments:
options -- a cairo:font-options-t instance
metrics -- a cairo:hint-metrics-t value
Details:
The cairo:font-options-hint-metrics function gets the metrics hinting mode for the font options instance. The (setf cairo:font-options-hint-metrics) function sets the metrics hinting mode for the font options instance. This controls whether metrics are quantized to integers in device units. See the documentation for the cairo:hint-metrics-t enumeration for full details.
See also:
2025-1-29
Function cairo:font-options-variations (options)
Syntax:
(cairo:font-options-variations options) => variations
(setf (cairo:font-options-variations options) variations)
Arguments:
options -- a cairo:font-options-t instance
variations -- a string with the font variations, or nil
Details:
The cairo:font-options-variations function gets the OpenType font variations for the font options instance. The (setf cairo:font-options-variations) function sets the OpenType font variations for the font options instance. The returned string belongs to the font options instance and must not be modified. It is valid until either the font options instance is destroyed or the font variations in the font options instance is modified.

Font variations are specified as a string with a format that is similar to the CSS font-variation-settings. The string contains a comma-separated list of axis assignments, which each assignment consists of a 4-character axis name and a value, separated by whitespace and optional equals sign.
Examples:
wght=200, wdth=140.5
wght 200, wdth 140.5    
See also:
2025-1-29
Function cairo:font-options-color-mode (options)
Syntax:
(cairo:font-options-color-mode options) => mode
(setf (cairo:font-options-color-mode options) mode)
Arguments:
options -- a cairo:font-options-t instance
mode -- a cairo:color-mode-t value for the color mode for the font options instance
Details:
The cairo:font-options-color-mode function gets the color mode for the font options instance. The (setf cairo:font-options-color-mode) function sets the color mode. This controls whether color fonts are to be rendered in color or as outlines. See the documentation for the cairo:color-mode-t enumeration for full details.

Since 1.18
See also:
2025-1-29
Function cairo:font-options-color-palette (options)
Syntax:
(cairo:font-options-color-palette options) => index
(setf (cairo:font-options-color-palette options) index)
Arguments:
options -- a cairo:font-options-t instance
index -- an unsigned integer for the palette index
Details:
The cairo:font-options-color-palette function gets the current OpenType color font palette for the font options instance. The (setf cairo:font-options-color-palette) function sets the OpenType font color palette. OpenType color fonts with a CPAL table may contain multiple palettes. The default color palette index is 0.

If index is invalid, the default palette is used.

Individual colors within the palette may be overriden with the cairo:font-options-custom-palette-color function.

Since 1.18
See also:
2025-1-29
Function cairo:font-options-custom-palette-color (options index)
Syntax:
(cairo:font-options-custom-palette-color options) => red, green, blue, alpha
(setf (cairo:font-options-custom-palette-color options) (list red green blue alpha))
Arguments:
options -- a cairo:font-options-t instance
index -- an unsigned integer for the index of the color to get
red -- a number for the red component of the color
green -- a number for the green component of the color
blue -- a number for the blue component of the color
alpha -- a number for the alpha component of the color
Details:
The cairo:font-options-custom-palette-color function gets the custom palette color for the color index for the font options instance. Returns nil if no custom color exists for the color index.

The (setf cairo:font-options-custom-palette-color) function sets a custom palette color for the font options instance. This overrides the palette color at the specified color index. This override is independent of the selected palette index and will remain in place even if the cairo:font-options-color-palette function is called to change the palette index.

It is only possible to override color indexes already in the font palette.

Since 1.18
Notes:
The arguments are coerced to double floats before being passed to the foreign C functions.
See also:
2025-1-29

Surfaces

Introduction to Cairo Devices

Devices are the abstraction Cairo employs for the rendering system used by a cairo:surface-t instance. You can get the device of a surface using the cairo:surface-device function.

Devices are created using custom functions specific to the rendering system you want to use. See the documentation for the surface types for those functions.

An important function that devices fulfill is sharing access to the rendering system between Cairo and your application. If you want to access a device directly that you used to draw to with Cairo, you must first call the cairo:device-flush function to ensure that Cairo finishes all operations on the device and resets it to a clean state.

Cairo also provides the cairo:device-acquire and cairo:device-release functions to synchronize access to the rendering system in a multithreaded environment. This is done internally, but can also be used by applications.

Putting this all together, a function that works with devices should look something like this:
(defun my-device-modifying-function (device)
  (let (status)
    ;; Ensure the device is properly reset
    (cairo:device-flush device)
    ;; Try to aquire the device
    (unless (eq :success
                (setf status
                      (cairo:device-aquire device)))
      (warn "Failed to aquire the device: ~a" (cairo:status-to-string status))
      (return-from my-device-modifying-function))

;; Do the custom operations on the device here. ;; But do not call any Cairo functions that might acquire devices.

;; Release the device when done. (cairo:device-release device)))
Note: Please refer to the documentation of each backend for additional usage requirements, guarantees provided, and interactions with existing surface API of the device functions for surfaces of that type.

Types and functions for Cairo Devices

CEnum cairo:device-type-t
Declaration:
(cffi:defcenum device-type-t
  :drm
  :gl
  :script
  :xcb
  :xlib
  :xml
  :cogl
  :win32
  (:invalid -1))  
Values:
:drm
The device is of type Direct Render Manager.
:gl
The device is of type OpenGL.
:script
The device is of type script.
:xcb
The device is of type xcb.
:xlib
The device is of type xlib.
:xml
The device is of type XML.
:cogl
The device is of type cogl.
:win32
The device is of type win32.
:invalid
The device is invalid.
Details:
The cairo:device-type-t enumeration is used to describe the type of a given device. The device types are also known as "backends" within Cairo. The device type can be queried with the cairo:device-type function.

The various cairo:device-t functions can be used with devices of any type, but some backends also provide type specific functions that must only be called with a device of the appropriate type. The behavior of calling a type specific function with a device of the wrong type is undefined.
Notes:
The only device type implemented in the Lisp API is the :script device type. See the cairo:with-script-surface documentation for an example that uses a script surface.
See also:
2025-1-18
CStruct cairo:device-t
Details:
The cairo:device-t structure represents the driver interface for drawing operations to a cairo:surface-t instance. There are different subtypes of cairo:device-t structures for different drawing backends.

The type of a device can be queried with the cairo:device-type function. Memory management of the cairo:device-t structure is done with the cairo:device-reference and cairo:device-destroy functions.
See also:
2025-1-18
Function cairo:device-reference (device)
Arguments:
device -- a cairo:device-t instance
Returns:
The referenced cairo:device-t instance.
Details:
Increases the reference count on device by one. This prevents the device from being destroyed until a matching call to the cairo:device-destroy function is made.

The number of references to a cairo:device-t instance can be get using the cairo:device-reference-count function.
See also:
2025-1-18
Function cairo:device-reference-count (device)
Arguments:
device -- a cairo:device-t instance
Returns:
The unsigned integer with the current reference count of device. If the instance is a "nil" instance, 0 will be returned.
Details:
Returns the current reference count of the device.
See also:
2025-1-18
Function cairo:device-destroy (device)
Arguments:
device -- a cairo:device-t instance
Details:
Decreases the reference count on device by one. If the result is zero, then device and all associated resources are freed. See the cairo:device-reference function.

This function may acquire devices if the last reference was dropped.
See also:
2025-1-18
Function cairo:device-status (device)
Arguments:
device -- a cairo:device-t instance
Returns:
The cairo:status-t value with an error code if the device is in an error state.
Details:
Checks whether an error has previously occurred for this device.
See also:
2025-1-18
Function cairo:device-type (device)
Arguments:
device -- a cairo:device-t instance
Returns:
The cairo:device-type-t value for the type of device.
Details:
This function returns the type of the device. See the cairo:device-type-t enumeration for available types.
See also:
2025-1-18
Function cairo:device-finish (device)
Arguments:
device -- a cairo:device-t instance to finish
Details:
This function finishes the device and drops all references to external resources. All surfaces, fonts and other objects created for this device will be finished, too. Further operations on the device will not affect the device but will instead trigger a :device-finished error.

When the last call to the cairo:device-destroy function decreases the reference count to zero, Cairo will call the cairo:device-finish function if it has not been called already, before freeing the resources associated with the device.

This function may acquire devices.
See also:
2025-1-18
Function cairo:device-flush (device)
Arguments:
device -- a cairo:device-t instance
Details:
Finish any pending operations for the device and also restore any temporary modifications Cairo has made to the state of the device. This function must be called before switching from using the device with Cairo to operating on it directly with native APIs. If the device does not support direct access, then this function does nothing.

This function may acquire devices.
See also:
2025-1-18
Function cairo:device-acquire (device)
Arguments:
device -- a cairo:device-t instance
Returns:
The cairo:status-t value that is :success on success or an error code if the device is in an error state and could not be acquired.
Details:
Acquires the device for the current thread. This function will block until no other thread has acquired the device. After a successful call to the cairo:device-acquire function, a matching call to the cairo:device-release function is required.

If the return value is :sucess, you successfully acquired the device. From now on your thread owns the device and no other thread will be able to acquire it until a matching call to the cairo:device-release function. It is allowed to recursively acquire the device multiple times from the same thread.
Notes:
You must never acquire two different devices at the same time unless this is explicitly allowed. Otherwise the possibility of deadlocks exist.

As various Cairo functions can acquire devices when called, these functions may also cause deadlocks when you call them with an acquired device. So you must not have a device acquired when calling them. These functions are marked in the documentation.
See also:
2025-1-29
Function cairo:device-release (device)
Arguments:
device -- a cairo:device-t instance
Details:
Releases a device previously acquired using the cairo:device-acquire function. See that function for details.
See also:
2025-1-29

Introduction to Cairo Surfaces

The cairo:surface-t structure is the abstract type representing all different drawing targets that cairo can render to. The actual drawings are performed using a Cairo context. A Cairo surface is created by using backend-specific constructors, typically of the form cairo:backend-surface-create.

Most surface types allow accessing the surface without using Cairo functions. If you do this, keep in mind that it is mandatory that you call the cairo:surface-flush function before reading from or writing to the surface and that you must use the cairo:surface-mark-dirty function after modifying it.

Example. Directly modifying an image surface
(defun modify-image-surface (surface)
  (let ((data (cairo:image-surface-data surface))
        (width (cairo:image-surface-width surface))
        (height (cairo:image-surface-height surface))
        (stride (cairo:image-surface-stride surface)))

;; flush to ensure all writing to the image was done (cairo:surface-flush surface)

;; modify the image (modify-image-data data width height stride)

;; mark the image dirty so Cairo clears its caches (cairo:surface-mark-dirty surface)))
Note that for other surface types it might be necessary to acquire the device of the surface first. See the cairo:device-acquire function for a discussion of devices.

Functions and types for Cairo Surfaces

CEnum cairo:content-t
Declaration:
(cffi:defcenum content-t
  (:color #x1000)
  (:alpha #x2000)
  (:color-alpha #x3000))  
Values:
:color
The surface will hold color content only.
:alpha
The surface will hold alpha content only.
:color-alpha
The surface will hold color and alpha content.
Details:
The cairo:content-t enumeration is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both.
Notes:
The large values here are designed to keep cairo:content-t values distinct from cairo:format-t values so that the implementation can detect the error if users confuse the two types.
See also:
2025-1-18
CEnum cairo:surface-type-t
Declaration:
(cffi:defcenum surface-type-t
  :image
  :pdf
  :ps
  :xlib
  :xcb
  :glitz
  :quartz
  :win32
  :beos
  :directfb
  :svg
  :os2
  :win32-printing
  :quartz-image
  :script
  :qt
  :recording
  :vg
  :gl
  :drm
  :tee
  :xml
  :skia
  :subsurface
  :cogl)  
Values:
:image
The surface is of type image.
:pdf
The surface is of type pdf.
:ps
The surface is of type ps.
:xlib
The surface is of type xlib.
:xcb
The surface is of type xcb.
:glitz
The surface is of type glitz. Deprecated 1.18: glitz support have been removed, this surface type will never be set by Cairo.
:quartz
The surface is of type quartz.
:win32
The surface is of type win32.
:beos
The surface is of type beos. Deprecated 1.18: beos support have been removed, this surface type will never be set by Cairo.
:directfb
The surface is of type directfb. Deprecated 1.18: directfb support have been removed, this surface type will never be set by Cairo.
:svg
The surface is of type svg.
:os2
The surface is of type os2. Deprecated 1.18: os2 support have been removed, this surface type will never be set by Cairo.
:win32-printing
The surface is a win32 printing surface.
:quartz-image
The surface is of type quartz_image.
:script
The surface is of type script.
:qt
The surface is of type Qt. Deprecated 1.18: Ot support have been removed, this surface type will never be set by Cairo.
:recording
The surface is of type recording.
:vg
The surface is a OpenVG surface. Deprecated 1.18: OpenVG support have been removed, this surface type will never be set by Cairo.
:gl
The surface is of type OpenGL. Deprecated 1.18: OpenGL support have been removed, this surface type will never be set by Cairo.
:drm
The surface is of type Direct Render Manager. Deprecated 1.18: DRM support have been removed, this surface type will never be set by Cairo.
:tee
The surface is of type 'tee' (a multiplexing surface).
:xml
The surface is of type XML (for debugging).
:skia
The surface is of type Skia. Deprecated 1.18: Skia support have been removed, this surface type will never be set by Cairo.
:subsurface
The surface is a subsurface created with the cairo:surface-create-for-rectangle function.
:cogl
This surface is of type Cogl. Deprecated 1.18: Cogl support have been removed, this surface type will never be set by Cairo.
Details:
The cairo:surface-type-t enumeration is used to describe the type of a given surface. The surface types are also known as "backends" or "surface backends" within Cairo. The type of a surface is determined by the function used to create it, which will generally be of the form cairo:type-surface-create, though see the cairo:surface-create-similar function as well. The surface type can be queried with the cairo:surface-type function.

The various cairo:surface-t functions can be used with surfaces of any type, but some backends also provide type-specific functions that must only be called with a surface of the appropriate type. These functions have names that begin with cairo:type-surface such as the cairo:image-surface-width function.

The behavior of calling a type-specific function with a surface of the wrong type is undefined.
Notes:
In the Lisp API support for the following surface types is currently available: :image, :pdf, :ps, :svg, :script, :recording, and :subsurface.
See also:
2025-1-18
CStruct cairo:surface-t
Returned by:
Details:
The cairo:surface-t structure represents an image, either as the destination of a drawing operation or as source when drawing onto another surface. To draw to a cairo:surface-t instance, create a Cairo context with the surface as the target, using the cairo:create function.

There are different subtypes of a cairo:surface-t structure for different drawing backends. For example, the cairo:image-surface-create function creates a bitmap image in memory. The type of a surface can be queried with the cairo:surface-type function.

The initial contents of a surface after creation depend upon the manner of its creation. If Cairo creates the surface and backing storage for the user, it will be initially cleared, for example, the cairo:image-surface-create and cairo:surface-create-similar functions. Alternatively, if the user passes in a reference to some backing storage and asks Cairo to wrap that in a cairo:surface-t structure, then the contents are not modified, for example, the cairo:image-surface-create-for-data function.

Memory management of a cairo:surface-t structure is done with the cairo:surface-reference and cairo:surface-destroy functions.
See also:
2025-1-18
Macro cairo:with-surface ((surface &rest args) &body body)
Syntax:
(cairo:with-surface (surface target content width height) body) => result
(cairo:with-surface (surface target format width height) body) => result
(cairo:with-surface (surface target x y width height) body) => result
Arguments:
surface -- a cairo:surface-t instance to create and initialize
target -- an existing cairo:surface-t instance used to select the backend of the new surface
content -- a cairo:content-t value for the content for the new surface
format -- a cairo:format-t value for the format of pixels in the surface to create
x -- a number coerced to a double float for the x origin of the subsurface from the top-left of the target surface, in device-space units
y -- a number coerced to a double float for the y origin of the subsurface from the top-left of the target surface, in device-space units
width -- a number coerced to a double float for the width of the subsurface, in device-space units
height -- a number coerced to a double float for the height of the subsurface, in device-space units
Details:
The cairo:with-surface macro allocates a new cairo:surface-t instance, initializes the Cairo surface with the given values and executes the body that uses the Cairo surface. After execution of the body the allocated memory for the Cairo surface is released. See the documentation of the cairo:surface-create-similar, cairo:surface-create-similar-image and cairo:surface-create-for-rectangle functions for more information about the initialization of the new Cairo surface.
See also:
2025-1-18
Macro cairo:with-context-for-surface ((context &rest args) &body body)
Syntax:
(cairo:with-context-for-surface (context target content width height) body) => result
(cairo:with-context-for-surface (context target format width height) body) => result
(cairo:with-context-for-surface (context target x y width height) body) => result
Arguments:
context -- a cairo:context-t instance to create and initialize
surface -- a cairo:surface-t instance to create and initialize
target -- an existing cairo:surface-t instance used to select the backend of the new surface
content -- a cairo:content-t value for the content for the new surface
format -- a cairo:format-t value for the format of pixels in the surface to create
x -- a number coerced to a double float for the x origin of the subsurface from the top-left of the target surface, in device-space units
y -- a number coerced to a double float for the y origin of the subsurface from the top-left of the target surface, in device-space units
width -- a number coerced to a double float for the width of the subsurface, in device-space units
height -- a number coerced to a double float for the height of the subsurface, in device-space units
Details:
The cairo:with-context-for-surface macro allocates a new cairo:context-t instance for a surface, initializes the Cairo context with the given values and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo context is released.

The context is created with the cairo:create function and destroyed with the cairo:destroy function. The context uses a surface that is created with one of the cairo:surface-create-similar, cairo:surface-create-similar-image, or cairo:surface-create-for-rectangle functions. You can access the cairo:surface-t instance for the created context with the cairo:target function. See also the cairo:with-surface macro.
See also:
2025-1-18
Function cairo:surface-create-similar (target content width height)
Arguments:
target -- an existing cairo:surface-t instance used to select the backend of the new surface
content -- a cairo:content-t value for the content for the new surface
width -- an integer for the width of the new surface, in device-space units
height -- an integer for the height of the new surface, in device-space units
Returns:
The newly allocated cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid surface, but it will return a "nil" surface if target is already in an error state or any other error occurs.
Details:
Create a new surface that is as compatible as possible with an existing surface. For example the new surface will have the same fallback resolution and font options as target. Generally, the new surface will also use the same backend as target, unless that is not possible for some reason. The type of the returned surface may be examined with the cairo:surface-type function.

Initially the surface contents are all 0 and transparent if contents have transparency, black otherwise.

Use the cairo:surface-create-similar-image function if you need an image surface which can be painted quickly to the target surface.
See also:
2025-1-18
Function cairo:surface-create-similar-image (target format width height)
Arguments:
target -- an existing cairo:surface-t instance used to select the preference of the new surface
format -- a cairo:format-t value for the new surface
width -- an integer for the width of the new surface, in device-space units
height -- an integer for the height of the new surface, in device-space units
Returns:
The newly allocated image cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid surface, but it will return a "nil" surface if target is already in an error state or any other error occurs.
Details:
Create a new image surface that is as compatible as possible for uploading to and the use in conjunction with an existing surface. However, this surface can still be used like any normal image surface.

Initially the surface contents are all 0 and transparent if contents have transparency, black otherwise.

Use the cairo:surface-create-similar function if you do not need an image surface.
See also:
2025-1-18
Function cairo:surface-create-for-rectangle (target x y width height)
Arguments:
target -- an existing cairo:surface-t instance for which the subsurface will point to
x -- a number coerced to a double float for the x origin of the subsurface from the top-left of the target surface, in device-space units
y -- a number coerced to a double float for the y origin of the subsurface from the top-left of the target surface, in device-space units
width -- a number coerced to a double float for the width of the subsurface, in device-space units
height -- a number coerced to a double float for the height of the subsurface, in device-space units
Returns:
The newly allocated cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid surface, but it will return "nil" surface if target is already in an error state or any other error occurs.
Details:
Create a new surface that is a rectangle within the target surface. All operations drawn to this surface are then clipped and translated onto the target surface. Nothing drawn via this subsurface outside of its bounds is drawn onto the target surface, making this a useful method for passing constrained child surfaces to library routines that draw directly onto the parent surface, that is with no further backend allocations, double buffering or copies.
Notes:
The semantics of subsurfaces have not been finalized yet unless the rectangle is in full device units, is contained within the extents of the target surface, and the target or device of the subsurface transforms are not changed.
See also:
2025-1-18
Function cairo:surface-reference (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The referenced cairo:surface-t instance.
Details:
Increases the reference count on surface by one. This prevents surface from being destroyed until a matching call to the cairo:surface-destroy function is made.

The number of references to a cairo:surface-t instance can be get using the cairo:surface-reference-count function.
See also:
2025-1-18
Function cairo:surface-reference-count (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The current reference count of surface. If the instance is a "nil" surface, 0 will be returned.
Details:
Returns the current reference count of surface.
See also:
2025-1-18
Function cairo:surface-destroy (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
Decreases the reference count on surface by one. If the result is zero, then surface and all associated resources are freed. See the cairo:surface-reference function.
See also:
2025-1-18
Function cairo:surface-status (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:status-t value for surface.
Details:
Checks whether an error has previously occurred for this surface. Possible values are :success, :null-pointer, :no-memory, :read-error, :invalid-content, :invalid-format, or :invalid-visual.
See also:
2025-1-18
Function cairo:surface-type (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:surface-type-t value for surface.
Details:
This function returns the type of the backend used to create the surface. See the cairo:surface-type-t enumeration for available types.
See also:
2025-1-18
Function cairo:surface-finish (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
This function finishes the surface and drops all references to external resources. For example, for the Xlib backend it means that Cairo will no longer access the drawable, which can be freed. After calling the cairo:surface-finish function the only valid operations on a surface are getting and setting user, referencing and destroying, and flushing and finishing it. Further drawing to the surface will not affect the surface but will instead trigger a :surface-finished error.

When the last call to the cairo:surface-destroy function decreases the reference count to zero, Cairo will call the cairo:surface-finish function if it has not been called already, before freeing the resources associated with the surface.
See also:
#2025-1-18
Function cairo:surface-flush (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
Do any pending drawing for the surface and also restore any temporary modifications Cairo has made to the state of the surface. This function must be called before switching from drawing on the surface with Cairo to drawing on it directly with native APIs. If the surface does not support direct access, then this function does nothing.
See also:
2025-1-18
Function cairo:surface-device (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:device-t instance with the device for surface or nil if the surface does not have an associated device.
Details:
This function returns the device for a surface. See the cairo:device-t documentation.
See also:
2025-1-18
Function cairo:surface-font-options (surface options)
Arguments:
surface -- a cairo:surface-t instance
options -- a cairo:font-options-t instance into which to store the retrieved options, all existing values are overwritten
Returns:
The cairo:font-options-t instance with the retrieved options.
Details:
Retrieves the default font rendering options for the surface. This allows display surfaces to report the correct subpixel order for rendering on them, print surfaces to disable hinting of metrics and so forth. The result can then be used with the cairo:scaled-font-create function.
See also:
2025-1-18
Function cairo:surface-content (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:content-t value with the content type of surface.
Details:
This function returns the content type of surface which indicates whether the surface contains color and/or alpha information. See the cairo:content-t enumeration.
See also:
2025-1-18
Function cairo:surface-mark-dirty (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
Tells Cairo that drawing has been done to surface using means other than Cairo, and that Cairo should reread any cached areas. Note that you must call the cairo:surface-flush function before doing such drawing.
See also:
#2025-1-18
Function cairo:surface-mark-dirty-rectangle (surface x y width height)
Arguments:
surface -- a cairo:surface-t instance
x -- an integerfor the x coordinate of dirty rectangle
y -- an integer for the y coordinate of dirty rectangle
width -- an integer for the width of dirty rectangle
height -- an integer for the height of dirty rectangle
Details:
Like the cairo:surface-mark-dirty function, but drawing has been done only to the specified rectangle, so that Cairo can retain cached contents for other parts of the surface. Any cached clip set on the surface will be reset by this function, to make sure that future Cairo calls have the clip set that they expect.
See also:
#2025-1-18
Function cairo:surface-device-offset (surface)
Syntax:
(cairo:surface-device-offset surface) => xoffset, yoffset
(setf (cairo:surface-device-offset surface) (list xoffset yoffset))
Arguments:
surface -- a cairo:surface-t instance
xoffset -- a number coerced to a double float for the offset in the x direction, in device units
yoffset -- a number coerced to a double float for the offset in the y direction, in device units
Details:
The cairo:surface-device-offset functions returns the device offset. The (setf cairo:surface-device-offset) function sets an offset that is added to the device coordinates determined by the current transformation matrix CTM when drawing to surface.

One use case for this function is when we want to create a cairo:surface-t instance that redirects drawing for a portion of an onscreen surface to an offscreen surface in a way that is completely invisible to the user of the Cairo API. Setting a transformation via the cairo:translate function is not sufficient to do this, since functions like the cairo:device-to-user function will expose the hidden offset.

Note that the offset affects drawing to the surface as well as using the surface in a source pattern.
See also:
2025-1-18
Function cairo:surface-device-scale (surface)
Syntax:
(cairo:surface-device-scale surface) => xscale, yscale
(setf (cairo:surface-device-scale surface) (list xscale yscale))
Arguments:
surface -- a cairo:surface-t instance
xscale -- a number coerced to a double float for the scale in the x direction, in device units
yscale -- a number coerced to a double float for the scale in the y direction, in device units
Details:
The cairo:surface-device-scale function returns the device scale. The (setf cairo:surface-device-scale) function sets a scale that is multiplied to the device coordinates determined by the current transformation matrix CTM when drawing to surface.

One common use for this is to render to very high resolution display devices at a scale factor, so that code that assumes 1 pixel will be a certain size will still work. Setting a transformation via the cairo:scale function is not sufficient to do this, since functions like the cairo:device-to-user function will expose the hidden scale.

Note that the scale affects drawing to the surface as well as using the surface in a source pattern.
See also:
2025-1-18
Function cairo:surface-fallback-resolution (surface)
Syntax:
(cairo:surface-fallback-resolution surface) => xpixels, ypixels
(setf (cairo:surface-fallback-resolution surface) (list xpixels ypixels))
Arguments:
surface -- a cairo:surface-t instance
xpixels -- a number coerced to a double float for the horizontal pixels per inch
ypixels -- a number coerced to a double float for the vertical pixels per inch
Details:
The cairo:surface-fallback-resolution function returns the fallback resolution, or default fallback resolution if never set. The (setf cairo:surface-fallback-resolution) function sets the horizontal and vertical resolution for image fallbacks.

When certain operations are not supported natively by a backend, Cairo will fallback by rendering operations to an image and then overlaying that image onto the output. For backends that are natively vector-oriented, this function can be used to set the resolution used for these image fallbacks. Larger values will result in more detailed images, but also larger file sizes.

Some examples of natively vector-oriented backends are the ps, pdf, and svg backends.

For backends that are natively raster-oriented, image fallbacks are still possible, but they are always performed at the native device resolution. So this function has no effect on those backends.

The default fallback resoultion is 300 pixels per inch in both dimensions.
Notes:
The fallback resolution only takes effect at the time of completing a page with the cairo:show-page or cairo:copy-page functions so there is currently no way to have more than one fallback resolution in effect on a single page.
See also:
2025-1-18
Function cairo:surface-copy-page (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
Emits the current page for backends that support multiple pages, but does not clear it, so that the contents of the current page will be retained for the next page. Use the cairo:surface-show-page function if you want to get an empty page after the emission.

There is a convenience function for this that takes a cairo:context-t context, namely the cairo:copy-page function.
See also:
#2025-1-18
Function cairo:surface-show-page (surface)
Arguments:
surface -- a cairo:surface-t instance
Details:
Emits and clears the current page for backends that support multiple pages. Use the cairo:surface-copy-page function if you do not want to clear the page.

There is a convenience function that takes a cairo:context-t instance, namely the cairo:show-page function.
See also:
2025-1-18

Introduction to Image Surfaces

Image surfaces provide the ability to render to memory buffers either allocated by Cairo or by the calling code. The supported image formats are those defined in the cairo:format-t enumeration.

Types and functions for Image Surfaces

CEnum cairo:format-t
Declaration:
(cffi:defcenum format-t
  (:invalid -1)
  (:argb32 0)
  (:rgb24 1)
  (:a8 2)
  (:a1 3)
  (:rgb16-565 4)
  (:rgb30 5)
  (:rgb96f 6)
  (:rgba128f 7))  
Values:
:invalid
No such format exists or is supported.
:argb32
Each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. That is, 50 % transparent red is 0x80800000, not 0x80ff0000.
:rgb24
Each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order.
:a8
Each pixel is a 8-bit quantity holding an alpha value.
:a1
Each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianess of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit.
:rgb16-565
Each pixel is a 16-bit quantity with red in the upper 5 bits, then green in the middle 6 bits, and blue in the lower 5 bits.
:rgb30
Like :rgb24 but with 10 bpc.
:rgb96f
3 floats, R, G, B. Since 1.18
:rgba128f
4 floats, R, G, B, A. Since 1.18
Details:
The cairo:format-t enumeration is used to identify the memory format of image data.
See also:
2025-1-18
Macro cairo:with-image-surface ((surface &rest args) &body body)
Syntax:
(cairo:with-image-surface (surface format width height) body) => result
Arguments:
surface -- a cairo:surface-t instance to create and initialize
format -- a cairo:format-t value for the format of pixels in the surface to create
width -- an integer for the width of the surface, in pixels
height -- an integer for the height of the surface, in pixels
Details:
The cairo:with-image-surface macro allocates a new cairo:surface-t instance, initializes the Cairo surface with the format, width, and height values and executes the body that uses the Cairo surface. After execution of the body the allocated memory for the Cairo surface is released. See the documentation of the cairo:image-surface-create function for more information about the initialization of the new Cairo surface.
See also:
2025-1-29
Macro cairo:with-context-for-image-surface ((context &rest args) &body body)
Syntax:
(cairo:with-context-for-image-surface (context format width height) body) => result
Arguments:
context -- a cairo:context-t instance to create and initialize
format -- a cairo:format-t value for the format of pixels in the surface to create
width -- an integer for the width of the surface, in pixels
height -- an integer for the height of the surface, in pixels
Details:
The cairo:with-context-for-image-surface macro allocates a new cairo:context-t instance for an image surface, initializes the Cairo context with the format, width, and height values and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo surface is released. See the documentation of the cairo:image-surface-create and cairo:create functions for more information about the initialization of the new Cairo context.
See also:
2025-1-29
Function cairo:image-surface-create (format width height)
Arguments:
format -- a cairo:format-t value with the format of pixels in the surface to create
width -- an integer for the width of the surface, in pixels
height -- an integer for the height of the surface, in pixels
Returns:
The newly created cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it.
Details:
Creates an image surface of the specified format and dimensions. Initially the surface contents are all 0. Specifically, within each pixel, each color or alpha channel belonging to the format will be 0. The contents of bits within a pixel, but not belonging to the given format are undefined.

This function always returns a valid surface, but it will return a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.
See also:
2025-1-29
Function cairo:image-surface-create-for-data (data format width height stride)
Arguments:
data -- a pointer to a buffer supplied by the application in which to write contents, this pointer must be suitably aligned for any kind of variable, for example, a pointer returned by malloc()
format -- a cairo:format-t value for the format of pixels in the surface to create
width -- an integer for the width of the image to be stored in the buffer
height -- an integer for the height of the image to be stored in the buffer
stride -- an integer for the number of bytes between the start of rows in the buffer as allocated, this value should always be computed by the cairo:format-stride-for-width function before allocating the data buffer
Returns:
The newly created cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid surface, but it will return a "nil" surface in the case of an error such as out of memory or an invalid stride value. In case of invalid stride value the error status of the returned surface will be :invalid-stride. You can use the cairo:surface-status function to check for this.
Details:
Creates an image surface for the provided pixel data. The output buffer must be kept around until the Cairo surface is destroyed or the cairo:surface-finish function is called on the surface. The initial contents of data will be used as the initial image contents. You must explicitly clear the buffer, using, for example, the cairo:rectangle and cairo:fill functions if you want it cleared.

Note that the stride may be larger than width x bytes per pixel to provide proper alignment for each pixel and row. This alignment is required to allow high-performance rendering within Cairo. The correct way to obtain a legal stride value is to call the cairo:format-stride-for-width function with the desired format and maximum image width value, and then use the resulting stride value to allocate the data and to create the image surface. See the cairo:format-stride-for-width function for example code.
See also:
2025-1-29
Function cairo:image-surface-data (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The pointer to the image data of this surface or nil if surface is not an image surface, or if the cairo:surface-finish function has been called.
Details:
Get the pointer to the data of the image surface, for direct inspection or modification. A call to the cairo:surface-flush function is required before accessing the pixel data to ensure that all pending drawing operations are finished. A call to the cairo:surface-mark-dirty function is required after the data is modified.
See also:
2025-1-29
Function cairo:image-surface-format (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The cairo:format-t value with the format of the surface.
Details:
Get the format of the image surface.
See also:
2025-1-29
Function cairo:image-surface-width (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The integer with the width of the surface in pixels.
Details:
Gets the width of the image surface in pixels.
See also:
2025-1-29
Function cairo:image-surface-height (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The integer with the height of the surface in pixels.
Details:
Gets the height of the image surface in pixels.
See also:
2025-1-29
Function cairo:image-surface-stride (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
The integer with the stride of the image surface in bytes, or 0 if surface is not an image surface.
Details:
Get the stride of the image surface in bytes. The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row.
See also:
2025-1-29
Function cairo:format-stride-for-width (format width)
Arguments:
format -- a cairo:format-t value
width -- an integer for the desired width of an image surface to be created.
Returns:
The integer with the appropriate stride to use given the desired format and width, or -1 if either the format is invalid or the width too large.
Details:
This function provides a stride value that will respect all Cairo alignment requirements of the accelerated image-rendering code within Cairo.
Examples:
Typical usage will be of the form:
(let* ((height 150)
       (width 200)
       (stride (cairo:format-stride-for-width :argb32 width))
       (data (g:malloc (* height stride)))
       (surface (cairo:image-surface-create-for-data data
                                                     :argb32
                                                     width
                                                     height
                                                     stride)))
  ... )    
See also:
2025-1-29

Introduction to PDF Surfaces

The PDF surface is used to render Cairo graphics to Adobe PDF files and is a multi-page vector surface backend.

The following mime types are supported: CAIRO_MIME_TYPE_JPEG, CAIRO_MIME_TYPE_JP2, CAIRO_MIME_TYPE_UNIQUE_ID, CAIRO_MIME_TYPE_JBIG2, CAIRO_MIME_TYPE_JBIG2_GLOBAL, CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS.

JBIG2 Images
JBIG2 data in PDF must be in the embedded format as described in ISO/IEC 11544. Image specific JBIG2 data must be in CAIRO_MIME_TYPE_JBIG2. Any global segments in the JBIG2 data (segments with page association field set to 0) must be in CAIRO_MIME_TYPE_JBIG2_GLOBAL. The global data may be shared by multiple images. All images sharing the same global data must set CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID to a unique identifier. At least one of the images must provide the global data using CAIRO_MIME_TYPE_JBIG2_GLOBAL. The global data will only be embedded once and shared by all JBIG2 images with the same CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID.

CCITT Fax Images
The CAIRO_MIME_TYPE_CCITT_FAX mime data requires a number of decoding parameters These parameters are specified using CAIRO_MIME_TYPE_CCITT_FAX_PARAMS. CAIRO_MIME_TYPE_CCITT_FAX_PARAMS mime data must contain a string of the form "param1=value1 param2=value2 ...".
Columns
An integer specifying the width of the image in pixels. [required]
Rows
An integer specifying the height of the image in scan lines. [required]
K
An integer identifying the encoding scheme used. < 0 is 2 dimensional Group 4, = 0 is Group 3 1 dimensional, > 0 is mixed 1 and 2 dimensional encoding. Default is 0. [optional]
EndOfLine
If true end-of-line bit patterns are present. Default is false. [optional]
EncodedByteAlign
If true the end of line is padded with 0 bits so the next line begins on a byte boundary. Default is false. [optional]
EndOfBlock
If true the data contains an end-of-block pattern. Default is true. [optional]
BlackIs1
If true 1 bits are black pixels. Default is false. [optional]
DamagedRowsBeforeError
An integer specifying the number of damages rows tolerated before an error occurs. Default is 0. [optional]
Boolean values may be "true" or "false", or 1 or 0.

These parameters are the same as the CCITTFaxDecode parameters in the PostScript Language Reference and Portable Document Format (PDF). Refer to these documents for further details.

An example CAIRO_MIME_TYPE_CCITT_FAX_PARAMS string is:
"Columns=10230 Rows=40000 K=1 EndOfLine=true EncodedByteAlign=1 BlackIs1=false"      

Types and functions for PDF surfaces

Bitfield cairo:pdf-outline-flags-t
Declaration:
(cffi:defbitfield pdf-outline-flags-t
  (:open 1)
  (:bold 2)
  (:italic 4))  
Values:
:open
The outline item defaults to open in the PDF viewer.
:bold
The outline item is displayed by the viewer in bold text.
:italic
The outline item is displayed by the viewer in italic text.
Details:
The cairo:pdf-outline-flags-t flags is used by the cairo:pdf-surface-add-outline function to specify the attributes of an outline item.
See also:
2025-1-13
CEnum cairo:pdf-metadata-t
Declaration:
(cffi:defcenum pdf-metadata-t
  :title
  :author
  :subject
  :keywords
  :creator
  :create-date
  :mod-date)  
Values:
:title
The document title.
:author
The document author.
:subject
The document subject.
:keywords
The document keywords.
:creator
The document creator.
:create-date
The document creation date.
:mod-date
The document modification date.
Details:
The cairo:pdf-metadata-t enumeration is used by the cairo:pdf-surface-set-metadata function to specify the metadata to set.
See also:
2025-1-13
CEnum cairo:pdf-version-t
Declaration:
(cffi:defcenum pdf-version-t
  :version-1-4
  :version-1-5
  #+cairo-1-18
  :version-1-6
  #+cairo-1-18
  :version-1-7)  
Values:
:version-1-4
The version 1.4 of the PDF specification.
:version-1-5
The version 1.5 of the PDF specification.
:version-1-6
The version 1.6 of the PDF specification.
:version-1-7
The version 1.7 of the PDF specification.
Details:
The cairo:pdf-version-t enumeration is used to describe the version number of the PDF specification that a generated PDF file will conform to.
See also:
2025-1-13
Macro cairo:with-pdf-surface ((surface path width height) &body body)
Syntax:
(cairo:with-pdf-surface (surface path width height) body) => result
Arguments:
surface -- a PDF cairo:surface-t instance
path -- a path or namestring with a filename for the PDF output, nil may be used to specify no output, this will generate a PDF surface that may be queried and used as a source, without generating a temporary file
width -- a number coerced to a double float for the width of the surface, in points (1 point == 1/72 inch)
height -- a number coerced to a double float for the height of the surface, in points (1 point == 1/72 inch)
Details:
The cairo:with-pdf-surface macro allocates a new PDF cairo:surface-t instance for the given path, width, and height values and executes the body that uses the PDF surface. After execution of the body the allocated memory for the PDF surface is released.
See also:
2025-1-13
Macro cairo:with-context-for-pdf-surface ((context path width height) &body body)
Syntax:
(cairo:with-context-for-pdf-surface (context format width height) body) => result
Arguments:
context -- a cairo:context-t instance to create and initialize
path -- a path or namestring with a filename for the PDF output, nil may be used to specify no output, this will generate a PDF surface that may be queried and used as a source, without generating a temporary file
width -- a number coerced to a double float for the width of the surface, in points (1 point == 1/72 inch)
height -- a number coerced to a double float for the height of the surface, in points (1 point == 1/72 inch)
Details:
The cairo:with-context-for-pdf-surface macro allocates a new cairo:context-t instance for a PDF surface, initializes the Cairo context with the path, width, and height values and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo context is released. See the documentation of the cairo:pdf-surface-create and cairo:create functions for more information about the initialization of the new Cairo context.
See also:
2025-1-13
Function cairo:pdf-surface-create (path width height)
Arguments:
path -- a namestring or pathname with a path for the PDF output (must be writable), nil may be used to specify no output, this will generate a PDF surface that may be queried and used as a source, without generating a temporary file
width -- a double float for the width of the surface, in points (1 point == 1/72.0 inch)
height -- a double float for the height of the surface, in points (1 point == 1/72.0 inch)
Returns:
The newly created cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.
Details:
Creates a PDF surface of the specified size in points to be written to filename.
See also:
2025-1-13
Function cairo:pdf-surface-restrict-to-version (surface version)
Arguments:
surface -- a PDF cairo:surface-t instance
version -- a cairo:pdf-version-t value
Details:
Restricts the generated PDF file to the given version. See the cairo:pdf-versions function for a list of available version values that can be used here. This function should only be called before any drawing operations have been performed on the given surface. The simplest way to do this is to call this function immediately after creating the surface.
See also:
2025-1-13
Function cairo:pdf-versions ()
Returns:
The list of cairo:pdf-version-t values with the supported versions.
Details:
Used to retrieve the list of supported versions. See the cairo:pdf-surface-restrict-to-version function.
See also:
2025-1-13
Function cairo:pdf-version-to-string (version)
Arguments:
version -- a cairo:pdf-version-t value
Returns:
The string with the given version.
Details:
Gets the string representation of the given version ID. This function will return nil if version is not valid. See the cairo:pdf-versions function for a way to get the list of valid version IDs.
See also:
2025-1-13
Function cairo:pdf-surface-set-size (surface width height)
Arguments:
surface -- a cairo:surface-t instance
width -- a number coerced to a double float for the new surface width, in points (1 point == 1/72.0 inch)
height -- a number coerced to a double float for the new surface height, in points (1 point == 1/72.0 inch)
Details:
Changes the size of a PDF surface for the current (and subsequent) pages. This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either the cairo:show-page or cairo:copy-page functions.
See also:
2025-1-13
Function cairo:pdf-surface-add-outline (surface parent utf8 link flags)
Arguments:
surface -- a cairo:surface-t instance
parent -- an integer for the ID of the parent item of 0 if this is a top level item
utf8 -- a string for the name of the outline
link -- a string for the link attributes specifying where this outline links to
flags -- a cairo:pdf-outline-flags-t value for the outline flags
Returns:
The integer with the ID for the added item.
Details:
Add an item to the document outline hierarchy with the name utf8 that links to the location specified by link. Link attributes have the same keys and values as the Link Tag, excluding the "rect" attribute. The item will be a child of the item with ID parent. Use the 0 value as the parent ID of toplevel items.
See also:
2025-1-13
Function cairo:pdf-surface-set-metadata (surface metadata utf8)
Arguments:
surface -- a cairo:surface-t instance
metadata -- a cairo:pdf-metadata-t value with the metadata item to set
utf8 -- a string for the metadata
Details:
Set document metadata. The :create-date and :mod-date values must be in ISO-8601 format: YYYY-MM-DDThh:mm:ss. An optional timezone of the form "[+/-]hh:mm}" or "Z" for UTC time can be appended. All other metadata values can be any UTF-8 string.
Examples:
(cairo:pdf-surface-set-metadata surface :title "My Document")
(cairo:pdf-surface-set-metadata surface :create-datea "2015-12-31T23:59+02:00")    
See also:
2025-1-13
Function cairo:pdf-surface-set-custom-metadata (surface name value)
Arguments:
surface -- a cairo:surface-t instance
name -- a string for the name of the custom metadata item to set (UTF8)
value -- a string for the value of the metadata (UTF8)
Details:
Set custom document metadata. The name argument may be any string except for the following names reserved by PDF: "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModDate", "Trapped".

If the value argument is nil or an empty string, the name metadata will not be set.
Examples:
(cairo:pdf-surface-set-custom-metadata surface "ISBN" "978-0123456789")    
Since 1.18
See also:
#2025-1-13
Function cairo:pdf-surface-set-page-label (surface utf8)
Arguments:
surface -- a cairo:surface-t instance
utf8 -- a string for the page label
Details:
Sets the page label for the current page.
See also:
2025-1-13
Function cairo:pdf-surface-set-thumbnail-size (surface width height)
Arguments:
surface -- a cairo:surface-t instance
width -- an integer for the thumbnail width
height -- an integer for the thumbnail height
Details:
Set the thumbnail image size for the current and all subsequent pages. Setting a width or height of 0 disables thumbnails for the current and subsequent pages.
See also:
2025-1-13

Introduction to PNG Support

The PNG functions allow reading PNG images into image surfaces, and writing any surface to a PNG file.

It is a toy API. It only offers very simple support for reading and writing PNG files, which is sufficient for testing and demonstration purposes. Applications which need more control over the generated PNG file should access the pixel data directly, using the cairo:image-surface-data function or a backend-specific access function, and process it with another library, for example GdkPixbuf or libpng.

Functions for PNG support

Function cairo:image-surface-create-from-png (path)
Arguments:
path -- a namestring or pathname for the path of the PNG file to load
Returns:
The new cairo:surface-t instance initialized with the contents of the PNG file, or a "nil" surface if any error occurred.
Details:
Creates a new image surface and initializes the contents to the given PNG file. A "nil" surface can be checked for with the cairo:surface-status function which may return one of the following values: :no-memory, :file-not-found, or :read-error. Alternatively, you can allow errors to propagate through the drawing operations and check the status on the context upon completion using the cairo:status function.
See also:
2025-1-13
Function cairo:surface-write-to-png (surface path)
Arguments:
surface -- a cairo:surface-t instance for pixel contents
path -- a namestring or pathname for the path of a file to write to
Returns:
:success if the PNG file was written successfully. Otherwise, :no-memory if memory could not be allocated for the operation or :surface-type-mismatch if the surface does not have pixel contents, or :write-error if an I/O error occurs while attempting to write the file.
Details:
Writes the contents of the image surface to a new file as a PNG image.
See also:
2025-1-13

Indroduction to PostScript Surfaces

The PostScript surface is used to render Cairo graphics to Adobe PostScript files and is a multi-page vector surface backend.

The following mime types are supported: CAIRO_MIME_TYPE_JPEG, CAIRO_MIME_TYPE_UNIQUE_ID, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, CAIRO_MIME_TYPE_EPS, CAIRO_MIME_TYPE_EPS_PARAMS.

Source surfaces used by the PostScript surface that have a CAIRO_MIME_TYPE_UNIQUE_ID mime type will be stored in PostScript printer memory for the duration of the print job. The CAIRO_MIME_TYPE_UNIQUE_ID mime type should only be used for small frequently used sources.

The CAIRO_MIME_TYPE_CCITT_FAX and CAIRO_MIME_TYPE_CCITT_FAX_PARAMS mime types are documented in CCITT Fax Images.

Embedding EPS files
Encapsulated PostScript files can be embedded in the PS output by setting the CAIRO_MIME_TYPE_EPS mime data on a surface to the EPS data and painting the surface. The EPS will be scaled and translated to the extents of the surface the EPS data is attached to.

The CAIRO_MIME_TYPE_EPS mime type requires the CAIRO_MIME_TYPE_EPS_PARAMS mime data to also be provided in order to specify the embeddding parameters. CAIRO_MIME_TYPE_EPS_PARAMS mime data must contain a string of the form "bbox=[llx lly urx ury]" that specifies the bounding box (in PS coordinates) of the EPS graphics. The parameters are: lower left x, lower left y, upper right x, upper right y. Normally the bbox data is identical to the %%BoundingBox data in the EPS file.

Type and functions for PostScript Surfaces

CEnum cairo:ps-level-t
Declaration:
(cffi:defcenum ps-level-t
  :level-2
  :level-3)  
Values:
:level-2
The language level 2 of the PostScript specification.
:level-3
The language level 3 of the PostScript specification.
Details:
The cairo:ps-level-t enumeration is used to describe the language level of the PostScript Language Reference that a generated PostScript file will conform to.
See also:
2025-1-29
Macro cairo:with-ps-surface ((surface path width height) &body body)
Syntax:
(cairo:with-ps-surface (surface path width height) body) => result
Arguments:
surface -- a PostScript cairo:surface-t instance
path -- a path or namestring for a filename for the PS output, nil may be used to specify no output, this will generate a PS surface that may be queried and used as a source, without generating a temporary file
width -- a number coerced to a double float for the width of the surface, in points (1 point == 1/72 inch)
height -- a number coerced to a double float for the height of the surface, in points (1 point == 1/72 inch)
Details:
The cairo:with-ps-surface macro allocates a new PostScript cairo:surface-t instance for the given path, width, and height values and executes the body that uses the PostScript surface. After execution of the body the allocated memory for the PostScript surface is released.
See also:
2025-1-29
Function cairo:ps-surface-create (path width height)
Arguments:
path -- a path or namestring for a filename for the PS output, nil may be used to specify no output, this will generate a PS surface that may be queried and used as a source, without generating a temporary file
width -- a number coerced to a double float for the width of the surface, in points (1 point == 1/72 inch)
height -- a number coerced to a double float for the height of the surface, in points (1 point == 1/72 inch)
Returns:
The newly created PostScript cairo:surface-t instance.
Details:
Creates a PostScript surface of the specified size in points to be written to path. The caller owns the surface and should call the cairo:surface-destroy function when done with it.

This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.

Note that the size of individual pages of the PostScript output can vary. See the cairo:ps-surface-set-size function.
See also:
2025-1-29
Function cairo:ps-surface-restrict-to-level (surface level)
Arguments:
surface -- a PostScript cairo:surface-t instance
level -- a cairo:ps-level-t value
Details:
Restricts the generated PostSript file to level. See the cairo:ps-levels function for a list of available level values that can be used here.

This function should only be called before any drawing operations have been performed on the given surface. The simplest way to do this is to call this function immediately after creating the surface.
See also:
2025-1-29
Function cairo:ps-levels ()
Returns:
The list of cairo:ps-level-t values with the supported levels.
Details:
Used to retrieve the list of supported levels. See the cairo:ps-surface-restrict-to-level function.
See also:
2025-1-29
Function cairo:ps-level-to-string (level)
Arguments:
level -- an integer for the level ID
Returns:
The string associated to the given level.
Details:
Get the string representation of the given level ID. This function will return nil if level ID is not valid. See the cairo:ps-levels function for a way to get the list of valid level IDs.
Examples:
Get the string representations for the supported levels.
(mapcar #'cairo:ps-level-to-string (cairo:ps-levels))
=> ("PS Level 2" "PS Level 3")    
See also:
2025-1-29
Function cairo:ps-surface-eps (surface)
Syntax:
(cairo:ps-surface-eps surface) => eps
(setf (cairo:ps-surface-eps surface) eps)
Arguments:
surface -- a PostScript cairo:surface-t instance
eps -- true if the surface will output Encasulated PostScript
Details:
The cairo:ps-surface-eps function checks whether the PostScript surface will output Encapsulated PostScript. The (setf cairo:ps-surface-eps) function will set if the PostScript surface will ouput Encapsulated PostScript.

This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface. An Encapsulated PostScript file should never contain more than one page.
See also:
2025-1-29
Function cairo:ps-surface-set-size (surface width height)
Arguments:
surface -- a PostScript cairo:surface-t instance
width -- a number coerced to a double float for the surface width, in points (1 point == 1/72 inch
height -- a number coerced to a double float for the surface height, in points
Details:
Changes the size of a PostScript surface for the current and subsequent pages.

This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either the cairo:show-page or cairo:copy-page function.
See also:
2025-1-29
Function cairo:ps-surface-dsc-begin-setup (surface)
Arguments:
surface -- a PostScript cairo:surface-t instance
Details:
This function indicates that subsequent calls to the cairo:ps-surface-dsc-comment function should direct comments to the Setup section of the PostScript output. This function should be called at most once per surface, and must be called before any call to the cairo:ps-surface-dsc-begin-page-setup function and before any drawing is performed to the surface.

See the cairo:ps-surface-dsc-comment function for more details.
See also:
2025-1-29
Function cairo:ps-surface-dsc-begin-page-setup (surface)
Arguments:
surface -- a PostScript cairo:surface-t instance
Details:
This function indicates that subsequent calls to the cairo:ps-surface-dsc-comment function should direct comments to the PageSetup section of the PostScript output.

This function call is only needed for the first page of a surface. It should be called after any call to the cairo:ps-surface-dsc-begin-setup and before any drawing is performed to the surface.

See the cairo:ps-surface-dsc-comment function for more details.
See also:
2025-1-29
Function cairo:ps-surface-dsc-comment (surface comment)
Arguments:
surface -- a PostScript cairo:surface-t instance
comment -- a comment string to be emitted into the PostScript output
Details:
Emit a comment into the PostScript output for the given surface. The comment is expected to conform to the PostScript Language Document Structuring Conventions (DSC). Please see that manual for details on the available comments and their meanings. In particular, the %%IncludeFeature comment allows a device-independent means of controlling printer device features. So the PostScript Printer Description Files Specification will also be a useful reference.

The comment string must begin with a percent character (%) and the total length of the string (including any initial percent characters) must not exceed 255 characters. Violating either of these conditions will place surface into an error state. But beyond these two conditions, this function will not enforce conformance of the comment with any particular specification.

The comment string should not have a trailing newline.

The DSC specifies different sections in which particular comments can appear. This function provides for comments to be emitted within three sections: the header, the Setup section, and the PageSetup section. Comments appearing in the first two sections apply to the entire document while comments in the BeginPageSetup section apply only to a single page.

For comments to appear in the header section, this function should be called after the surface is created, but before a call to the cairo:ps-surface-dsc-begin-setup function.

For comments to appear in the Setup section, this function should be called after a call to the cairo:ps-surface-dsc-begin-setup function but before a call to the cairo:ps-surface-dsc-begin-page-setup function.

For comments to appear in the PageSetup section, this function should be called after a call to the cairo:ps-surface-dsc-begin-page-setup function.

Note that it is only necessary to call the cairo:ps-surface-dsc-begin-page-setup function for the first page of any surface. After a call to the cairo:show-page or cairo:copy-page functions comments are unambiguously directed to the PageSetup section of the current page. But it does not hurt to call this function at the beginning of every page as that consistency may make the calling code simpler.

As a final note, Cairo automatically generates several comments on its own. As such, applications must not manually generate any of the following comments:
Header section:
%!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages, %%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.
Setup section:
%%BeginSetup, %%EndSetup
PageSetup section:
%%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.
Other sections:
%%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF
Examples:
Here is an example sequence showing how this function might be used:
(test cairo-ps-surface-dsc-comment
  (let* ((path (sys-path "out/comment.ps"))
         (width 100) (height 200)
         (surface (cairo:ps-surface-create path width height)))
    ;; Create a context for the surface
    (cairo:with-context (context surface)
      ;; Header page 1
      (cairo:ps-surface-dsc-comment surface "%%Title: My document")
      (cairo:ps-surface-dsc-comment surface
                                    "%%Copyright: Copyright (C) 2014 Crategus")
      ;; Setup page 1
      (cairo:ps-surface-dsc-begin-setup surface)
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *MediaColor White")
      ;; Page setup page 1
      (cairo:ps-surface-dsc-begin-page-setup surface)
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *PageSize A3")
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *InputSlot Capacity")
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *MediaType Glossy")
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *MediaColor Blue")
      ;; Draw to first page here
      ...
      ;; Show first page
      (cairo:show-page context)
      ;; Header page 2
      (cairo:ps-surface-dsc-comment surface
                                    "%%IncludeFeature: *PageSize A5")
      ;; Draw to second page here
      ...
      ;; Show second page
      (cairo:show-page context))
    (cairo:surface-destroy surface)))    
See also:
2025-1-29

Indroduction to Recording Surfaces

A recording surface is a surface that records all drawing operations at the highest level of the surface backend interface, that is, the level of paint, mask, stroke, fill, and text glyphs. The recording surface can then be "replayed" against any target surface by using it as a source surface.

If you want to replay a surface so that the results in target will be identical to the results that would have been obtained if the original operations applied to the recording surface had instead been applied to the target surface, you can use code like this:
(cairo:with-context (context target)
  (cairo:set-source-surface context recording-surface 0.0 0.0)
  (cairo:paint context)
  ...)      
A recording surface is logically unbounded, that is, it has no implicit constraint on the size of the drawing surface. However, in practice this is rarely useful as you wish to replay against a particular target surface with known bounds. For this case, it is more efficient to specify the target extents to the recording surface upon creation.

The recording phase of the recording surface is careful to snapshot all necessary objects, paths, patterns, etc., in order to achieve accurate replay.

Functions for Recording Surfaces

Macro cairo:with-recording-surface ((surface content &rest args) &body body)
Syntax:
(cairo:with-recording-surface (surface content) body) => result
(cairo:with-recording-surface (surface content x y width height) body) => result
Arguments:
surface -- a newly allocated cairo:surface-t instance
content -- a cairo:content-t value
x -- a number coerced to a double float for the x coordinate
y -- a number coerced to a double float for the y coordinate
width -- a number coerced to a double float for the width in pixels
height -- a number coerced to a double float for the height in pixels
Details:
The cairo:with-recording-surface macro allocates a new cairo:surface-t instance and executes the body that uses the Cairo surface. After execution of the body the allocated memory for the Cairo surface is released. This macro calls the cairo:recording-surface-create function to create the surface. If the optional x, y, width, height arguments are given a bounded recording surface is created, otherwise the recording surface is unbounded. For an unbounded recording surface the cairo:recording-surface-extents function returns a nil value.
See also:
2025-1-29
Macro cairo:with-context-for-recording-surface ((context &rest args) &body body)
Syntax:
(cairo:with-context-for-recording-surface (context content) body) => result
(cairo:with-context-for-recording-surface (context content x y width height) body) => result
Arguments:
context -- a cairo:context-t instance to create and initialize
content -- a cairo:content-t value
x -- a number coerced to a double float for the x coordinate
y -- a number coerced to a double float for the y coordinate
width -- a number coerced to a double float for the width in pixels
height -- a number coerced to a double float for the height in pixels
Details:
The cairo:with-context-for-recording-surface macro allocates a new cairo:context-t instance, initializes the Cairo context with the given values and executes the body that uses the Cairo context. After execution of the body the allocated memory for the Cairo surface is released. See the documentation of the cairo:recording-surface-create and cairo:create functions for more information about the initialization of the new Cairo context.
See also:
2025-1-29
Function cairo:recording-surface-create (content &key x y width height)
Arguments:
content -- a cairo:content-t value
x -- a number coerced to a double float for the x coordinate in pixels
y -- a number coerced to a double float for the y coordinate in pixels
width -- a number coerced to a double float for the width in pixels
height -- a number coerced to a double float for the height in pixels
Returns:
The newly created cairo:surface-t instance.
Details:
Creates a recording surface which can be used to record all drawing operations at the highest level, that is, the level of paint, mask, stroke, fill and text glyphs. If at least one keyword argument is given a bounded recording surface is created, otherwise the recording surface is unbounded. The default values for the keyword arguments are 0.0d0.

The recording surface can then be "replayed" against any target surface by using it as a source to drawing operations. The recording phase of the recording surface is careful to snapshot all necessary objects, paths, patterns, etc., in order to achieve accurate replay.

The caller owns the surface and should call the cairo:surface-destroy function when done with it.
See also:
2025-1-29
Function cairo:recording-surface-ink-extents (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
x -- a double float with the x coordinate of the top-left of the ink bounding box
y -- a double float with the y coordinate of the top-left of the ink bounding box
width -- a double float with the width of the the ink bounding box
height -- a double float with the height of the the ink bounding box
Details:
Measures the extents of the operations stored within the recording surface. This is useful to compute the required size of an image surface, or equivalent, into which to replay the full sequence of drawing operations.
See also:
2025-1-29
Function cairo:recording-surface-extents (surface)
Arguments:
surface -- a cairo:surface-t instance
Returns:
x -- a double float with the x coordinate of the top-left of the bounding box
y -- a double float with the y coordinate of the top-left of the bounding box
width -- a double float with the width of the the bounding box
height -- a double float with the height of the the bounding box
Details:
Get the extents of the recording surface. Returns false if the recorded surface is unbounded.
See also:
2025-1-29

Introduction to SVG Surfaces

The SVG surface is used to render Cairo graphics to SVG files and is a multi-page vector surface backend.

Types and functions for SVG surfaces

CEnum cairo:svg-version-t
Declaration:
(cffi:defcenum svg-version-t
  :version-1-1
  :version-1-2)  
Values:
:version-1-1
The version 1.1 of the SVG specification.
:version-1-2
The version 1.2 of the SVG specification.
Details:
The cairo:svg-version-t enumeration is used to describe the version number of the SVG specification that a generated SVG file will conform to.
See also:
2025-1-13
CEnum cairo:svg-unit-t
Declaration:
(cffi:defcenum svg-unit-t
  :user
  :em
  :ex
  :px
  :in
  :cm
  :mm
  :pt
  :pc
  :percent)  
Values:
:user
User unit, a value in the current coordinate system. If used in the root element for the initial coordinate systems it corresponds to pixels.
:em
The size of the element's font.
:ex
The x-height of the element’s font.
:px
Pixels (1px = 1/96th of 1in).
:in
Inches (1in = 2.54cm = 96px).
:cm
Centimeters (1cm = 96px/2.54).
:mm
Millimeters (1mm = 1/10th of 1cm).
:pt
Points (1pt = 1/72th of 1in).
:pc
Picas (1pc = 1/6th of 1in).
:percent
Percent, a value that is some fraction of another reference value.
Details:
The cairo:svg-unit-t enumeration is used to describe the units valid for coordinates and lengths in the SVG specification.

Since 1.16
See also:
2025-1-13
Function cairo:svg-surface-create (path width height)
Arguments:
path -- a namestring or pathname for a path for the SVG output (must be writable), nil may be used to specify no output, this will generate a SVG surface that may be queried and used as a source, without generating a temporary file
width -- a number coerced to a double float for the width of the surface, in points (1 point == 1/72.0 inch)
height -- a number coerced to a double float for the height of the surface, in points (1 point == 1/72.0 inch)
Returns:
The newly created cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.
Details:
Creates a SVG surface of the specified size in points to be written to path. The SVG surface backend recognizes the following MIME types for the data attached to a surface, see the cairo_surface_set_mime_data() function, when it is used as a source pattern for drawing on this surface: CAIRO_MIME_TYPE_JPEG, CAIRO_MIME_TYPE_PNG, and CAIRO_MIME_TYPE_URI. If any of them is specified, the SVG backend emits a href with the content of MIME data instead of a surface snapshot (PNG, Base64-encoded) in the corresponding image tag.

The unofficial MIME type CAIRO_MIME_TYPE_URI is examined first. If present, the URI is emitted as is: assuring the correctness of URI is left to the client code.

If CAIRO_MIME_TYPE_URI is not present, but CAIRO_MIME_TYPE_JPEG or CAIRO_MIME_TYPE_PNG is specified, the corresponding data is Base64-encoded and emitted.

If CAIRO_MIME_TYPE_UNIQUE_ID is present, all surfaces with the same unique identifier will only be embedded once.
See also:
2025-1-13
Function cairo:svg-surface-document-unit (surface)
Syntax:
(cairo:svg-surface-document-unit surface) => unit
(setf (cairo:svg-surface-document-unit surface) unit)
Arguments:
surface -- a cairo:surface-t instance
unit -- a cairo:svg-unit-t value
Details:
The cairo:svg-surface-document-unit function gets the unit of the SVG surface. If the surface passed as an argument is not a SVG surface, the function sets the error status to CAIRO_STATUS_SURFACE_TYPE_MISMATCH and returns CAIRO_SVG_UNIT_USER.

The (setf cairo:svg-surface-document-unit) function sets the unit for use with the specified width and height of the generated SVG file. See the cairo:svg-unit-t enumeration for a list of available unit values that can be used here.

This function can be called at any time before generating the SVG file.

However to minimize the risk of ambiguities it is recommended to call it before any drawing operations have been performed on the given surface, to make it clearer what the unit used in the drawing operations is. The simplest way to do this is to call this function immediately after creating the SVG surface.

Note if this function is never called, the default unit for SVG documents generated by cairo will be :pt. This is for historical reasons.
See also:
#2025-1-13
Function cairo:svg-surface-restrict-to-version (surface version)
Arguments:
surface -- a cairo:surface-t instance
version -- a cairo:svg-version-t value
Details:
Restricts the generated SVG file to version. See the cairo:svg-versions function for a list of available version values that can be used here. This function should only be called before any drawing operations have been performed on the given surface. The simplest way to do this is to call this function immediately after creating the surface.
See also:
#2025-1-13
Function cairo:svg-versions ()
Returns:
The list of cairo:svg-version-t values with the supported versions.
Details:
Used to retrieve the list of supported versions. See the cairo:svg-surface-restrict-to-version function.
See also:
#2025-1-13
Function cairo:svg-version-to-string (version)
Arguments:
version -- a cairo:svg-version-t value
Returns:
The string with the given version.
Details:
Gets the string representation of the given version ID. This function will return nil if version is not valid. See the cairo:svg-versions functions for a way to get the list of valid version IDs.
See also:
#2025-1-13

Indroduction to Script Surfaces

The script surface provides the ability to render to a native script that matches the Cairo drawing model. The scripts can be replayed using tools under the util/cairo-script directory, or with the cairo-perf-trace utility.

Types and functions for Script Surfaces

CEnum cairo:script-mode-t
Declaration:
(cffi:defcenum script-mode-t
  :ascii
  :binary)  
Values:
:ascii
The output will be in readable text (default).
:binary
The output will use byte codes.
Details:
A set of script output variants.
See also:
2025-1-29
Macro cairo:with-script-surface ((surface path content width height) &body body)
Syntax:
(cairo:with-script-surface (surface path content width height) body) => result
Arguments:
surface -- a newly allocated cairo:surface-t instance
path -- a path or namestring for the file to write the script to
content -- a cairo:content-t value
width -- a number coerced to a double float for the width in pixels
height -- a number coerced to a double float for the height in pixels
Details:
The cairo:with-script-surface macro allocates a new cairo:surface-t instance for a newly created cairo:device-t instance of :script type and executes the body that uses the Cairo script surface. After execution of the body the allocated memory for the Cairo surface and the Cairo device is released. This macro calls the cairo:script-create function to create the device and the cairo:script-surface-create function to create the surface.
Examples:
From the examples for the Cairo library, which shows how to use a script surface.
;; Draw a rectangle on a Cairo context
(defun draw-stroke (context width height)
  (cairo:save context)
  ;; Clear surface
  (cairo:set-source-rgb context 1.0 1.0 1.0)
  (cairo:paint context)
  ;; Example is in 1.0 x 1.0 coordinate space
  (cairo:scale context width height)
  ;; Drawing code goes here
  (setf (cairo:line-width context) 0.1)
  (cairo:set-source-rgb context 1.0 0.0 0.0)
  (cairo:rectangle context 0.25 0.25 0.5 0.5)
  (cairo:stroke context)
  (cairo:restore context))

;; Generate a script surface and call a draw function (defun demo-script-draw (&optional (drawfunc #'draw-stroke)) (let ((path (sys-path "out/script-draw.script")) (width 200) (height 200)) (cairo:with-script-surface (surface path :color width height) (cairo:with-context (context surface) (funcall drawfunc context width height) (cairo:surface-show-page surface)))))
This is the output of this example.
%!CairoScript
<< /content //COLOR /width 200 /height 200 >> surface context
1 g set-source
paint
n 50 50 100 100 rectangle
1 0 0 rgb set-source
200 200 scale
0.1 set-line-width
stroke+
show-page
pop    
See also:
2025-1-29
Function cairo:script-create (path)
Arguments:
path -- a path or namestring for the file to write the script to
Returns:
The newly created cairo:device-t instance.
Details:
Creates an output device for emitting the script, used when creating the individual surfaces. The caller owns the device and should call the cairo:device-destroy function when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" device if an error such as out of memory occurs. You can use the cairo:device-status function to check for this.
Notes:
Use the cairo:with-script-surface macro to create a Cairo surface for an output device.
See also:
2025-1-29
Function cairo:script-from-recording-surface (script surface)
Arguments:
script -- a cairo:device-t instance
surface -- a cairo:surface-t instance for the recording surface to replay
Returns:
The :success value on successful completion or an error code.
Details:
Converts the recorded operations in surface into a script.
See also:
2025-1-29
Function cairo:script-mode (script)
Syntax:
(cairo:script-mode script) => mode
(setf (cairo:script-mode script) mode)
Arguments:
script -- a cairo:device-t instance
mode -- a cairo:script-mode-t value
Details:
The cairo:script-mode function queries the script for its current output mode. The (setf cairo:script-mode) functions changes the output mode of the script.
See also:
2025-1-29
Function cairo:script-surface-create (script content width height)
Arguments:
script -- a cairo:device-t instance
content -- a cairo:content-t value
width -- a number coerced to a double float for the width in pixels
height -- a number coerced to a double float for the height in pixels
Returns:
The newly created cairo:surface-t instance.
Details:
Creates a new surface that will emit its rendering through script. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.
See also:
2025-1-29
Function cairo:script-surface-create-for-target (script target)
Arguments:
script -- a cairo:device-t instance
target -- a cairo:surface-t instance
Returns:
The newly created cairo:surface-t instance.
Details:
Creates a proxy surface that will render to target and record the operations to script. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use the cairo:surface-status function to check for this.
See also:
2025-1-29
Function cairo:script-write-comment (script comment)
Arguments:
script -- a cairo:device-t instance
comment -- a string with the comment to emit
Details:
Emit a string verbatim into the script.
See also:
2025-1-29

Utilities

Generic matrix operations

CStruct cairo:matrix-t
Declaration:
(cffi:defcstruct matrix-t
  (xx :double)
  (yx :double)
  (xy :double)
  (yy :double)
  (x0 :double)
  (y0 :double))  
Values:
xx
The double float with the xx component.
yx
The double float with the yx component.
xy
The double float with the xy component.
yy
The double float with the yy component.
x0
The double float with the x translation component.
y0
The double float with the y translation component.
Details:
The cairo:matrix-t structure holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (x,y) is given by:
xnew = xx * x + xy * y + x0
ynew = yx * x + yy * y + y0  
The current transformation matrix (CTM) of a cairo:context-t instance, represented as a cairo:matrix-t structure, defines the transformation from user space coordinates to device space coordinates. See also the cairo:matrix function.
See also:
2025-1-18
Macro cairo:with-matrix ((var &rest args) &body body)
Syntax:
(cairo:with-matrix (matrix) body) => result
(cairo:with-matrix (matrix rad) body) => result
(cairo:with-matrix (matrix :translate tx ty) body) => result
(cairo:with-matrix (matrix :scale sx sy) body) => result
(cairo:with-matrix (matrix xx yx xy yy x0 y0) body) => result
Arguments:
matrix -- a cairo:matrix-t instance to create and initialize
rad -- a number coerced to a double float for the angle of rotation, in radians
tx -- a number for the amount to tanslate in the x direction
ty -- a number for the amount to tanslate in the y direction
sx -- a number for the scale factor in the x direction
sy -- a number for the scale factor in the y direction
xx -- a number for the xx component of the transformation
yx -- a number for the yx component of the transformation
xy -- a number for the xy component of the transformation
yy -- a number for the yy component of the transformation
x0 -- a number for the x translation component of the transformation
y0 -- a number for the y translation component of the transformation
Details:
The cairo:with-matrix macro allocates a new cairo:matrix-t instance, initializes the matrix with the given values and executes the body that uses the matrix. After execution of the body the allocated memory for the matrix is released.

When no argument is given the matrix is initialized to the identity transformation with the cairo:matrix-init-identity function. The initialization with one argument initializes a rotation with the cairo:matrix-init-rotate function. The initialization with three arguments initializes a translation with the cairo:matrix-init-translate function or a transformation which scales with the cairo:matrix-init-scale function. When six numbers are given the matrix is initialized with the cairo:matrix-init function.
Notes:
The arguments are coerced to double floats before being passed to the foreign C functions.
See also:
2025-1-18
Macro cairo:with-matrices (vars &body body)
Syntax:
(cairo:with-matrices (matrix1 ... matrixn) body) => result
Arguments:
matrix1 ... matrixn -- newly created cairo:matrix-t instances
body -- a body that uses the bindings matrix1 ... matrixn
Details:
The cairo:with-matrices macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each matrix can be initialized with values using the syntax for the cairo:with-matrix macro. See also the cairo:with-matrix documentation.
See also:
2025-1-18
Function cairo:matrix-init (matrix xx yx xy yy x0 y0)
Arguments:
matrix -- a cairo:matrix-t instance to initialize
xx -- a number with the xx component of the transformation
yx -- a number with the yx component of the transformation
xy -- a number with the xy component of the transformation
yy -- a number with the yy component of the transformation
x0 -- a number with the x translation component of the transformation
y0 -- a number with the y translation component of the transformation
Returns:
The initialized cairo:matrix-t instance.
Details:
Sets the matrix to be the affine transformation given by the xx, yx, xy, yy, x0, y0 arguments. The transformation is given by:
xnew = xx * x + xy * y + x0
ynew = yx * x + yy * y + y0  
The cairo:with-matrix and cairo:with-matrices macros are more convenient for defining and initialising a matrix in one step.
Examples:
The cairo:matrix-t structure is a foreign CFFI type. Therefore, to create a matrix, we must define a foreign object:
(cffi:with-foreign-object (matrix '(:struct cairo:matrix-t))
  (cairo:matrix-init matrix 0.5 0.0 0.0 1.0 2.0 3.0)
  (cairo:matrix-to-float matrix))
=> (0.5d0 0.0d0 0.0d0 1.0d0 2.0d0 3.0d0)    
Defining and initialising a matrix with the cairo:with-matrix macro.
(cairo:with-matrix (matrix 1/2 0 0 1 2 3)
  (cairo:matrix-to-float matrix))
=> (0.5d0 0.0d0 0.0d0 1.0d0 2.0d0 3.0d0)    
Notes:
The arguments are coerced to double floats before being passed to the foreign C functions.
See also:
2025-1-18
Function cairo:matrix-init-identity (matrix)
Arguments:
matrix -- a cairo:matrix-t instance to initialize
Returns:
The cairo:matrix-t instance set to be an identity transformation.
Details:
Modifies the matrix to be an identity transformation.
Examples:
The cairo:with-matrix initialises the matrix to the identity transformation when no values are given.
(cairo:with-matrix (matrix)
  (cairo:matrix-to-float matrix))
=> (1.0d0 0.0d0 0.0d0 1.0d0 0.0d0 0.0d0)    
See also:
2025-1-18
Function cairo:matrix-init-translate (matrix tx ty)
Arguments:
matrix -- a cairo:matrix-t instance to initialize
tx -- a number coerced to a double float for the amount to tanslate in the x direction
ty -- a number coerced to a double float for the amount to tanslate in the y direction
Returns:
The initialized cairo:matrix-t instance.
Details:
Initializes the matrix to a transformation that translates by tx and ty in the x and y dimensions, respectively.
Examples:
The cairo:with-matrix macro uses this function for initialising the matrix for a translation.
(cairo:with-matrix (matrix :translate 1/2 2)
  (cairo:matrix-to-float matrix))
=> (1.0d0 0.0d0 0.0d0 1.0d0 0.5d0 2.0d0)    
See also:
2025-1-18
Function cairo:matrix-init-scale (matrix sx sy)
Arguments:
matrix -- a cairo:matrix-t instance to initialize
sx -- a number coerced to a double float for the scale factor in the x direction
sy -- a number coerced to a double float for the scale factor in the y direction
Returns:
The initialized cairo:matrix-t instance.
Details:
Initializes the matrix to a transformation that scales by sx and sy in the x and y dimensions, respectively.
Examples:
The cairo:with-matrix macro uses this function for initialising the matrix for a transformation that scales.
(cairo:with-matrix (matrix :scale  1/2 2)
  (cairo:matrix-to-float matrix))
=> (0.5d0 0.0d0 0.0d0 2.0d0 0.0d0 0.0d0)    
See also:
2025-1-18
Function cairo:matrix-init-rotate (matrix angle)
Arguments:
matrix -- a cairo:matrix-t instance to initialize
angle -- a number coerced to a double float for the angle of rotation, in radians
Returns:
The initialized cairo:matrix-t instance.
Details:
Initializes the matrix to a transformation that rotates by angle. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of Cairo, positive angles rotate in a clockwise direction.
Examples:
The cairo:with-matrix macro uses this function for initialising the matrix for a transformation that rotates.
(cairo:with-matrix (matrix (/ pi 2))
  (cairo:matrix-to-float matrix))
=> (6.123233995736766d-17 1.0d0 -1.0d0 6.123233995736766d-17 0.0d0 0.0d0)    
See also:
2025-1-18
Function cairo:matrix-to-float (matrix)
Arguments:
matrix -- a cairo:matrix-t instance
Returns:
The list with double floats for the components of the matrix.
Details:
Converts the matrix to a list of double floats.
Notes:
This function is a Lisp extension and not present in the C library.
See also:
2025-1-18
Function cairo:matrix-translate (matrix tx ty)
Arguments:
matrix -- a cairo:matrix-t instance
tx -- a number coerced to a double float for the amount to tanslate in the x direction
ty -- a number coerced to a double float for the amount to tanslate in the y direction
Returns:
The cairo:matrix-t instance with the applied translation.
Details:
Applies a translation by tx, ty to the transformation in the matrix. The effect of the new transformation is to first translate the coordinates by tx and ty, then apply the original transformation to the coordinates.
See also:
2025-1-18
Function cairo:matrix-scale (matrix sx sy)
Arguments:
matrix -- a cairo:matrix-t instance
sx -- a number coerced to a double float for the scale factor in the x direction
sy -- a number coerced to a double float for the scale factor in the y direction
Returns:
The cairo:matrix-t instance with the applied scaling.
Details:
Applies scaling by sx and sy to the transformation in the matrix. The effect of the new transformation is to first scale the coordinates by sx and sy, then apply the original transformation to the coordinates.
See also:
2025-1-18
Function cairo:matrix-rotate (matrix angle)
Arguments:
matrix -- a cairo:matrix-t instance
angle -- a number coerced to a double float for the angle of rotation, in radians
Returns:
The cairo:matrix-t instance with the applied rotation.
Details:
Applies rotation by angle to the transformation in the matrix. The effect of the new transformation is to first rotate the coordinates by angle, then apply the original transformation to the coordinates.

The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of Cairo, positive angles rotate in a clockwise direction.
See also:
2025-1-18
Function cairo:matrix-invert (matrix)
Arguments:
matrix -- a cairo:matrix-t instance
Returns:
The inversed cairo:matrix-t instance if matrix has an inverse, otherwise nil.
Details:
Changes the matrix to be the inverse of its original value. Not all transformation matrices have inverses. If the matrix collapses points together, it is degenerate, then it has no inverse and this function will fail.
See also:
2025-1-18
Function cairo:matrix-multiply (matrix a b)
Arguments:
matrix -- a cairo:matrix-t instance for the result
a -- a cairo:matrix-t instance
b -- a cairo:matrix-t instance
Returns:
The cairo:matrix-t instance with the result.
Details:
Multiplies the affine transformations in a and b together, The effect of the resulting transformation is to first apply the transformation in a to the coordinates and then apply the transformation in b to the coordinates.

It is allowable for matrix to be identical to either a or b.
See also:
2025-1-18
Function cairo:matrix-transform-distance (matrix dx dy)
Syntax:
(cairo:transform-distance matrix dx dy) => tdx, tdy
Arguments:
matrix -- a cairo:matrix-t instance
dx -- a number coerced to a double float for the x component of a distance vector
dy -- a number coerced to a double float for the y component of a distance vector
tdx -- a double float for the transformed x component of a distance vector
tdy -- a double float for the transformed y component of a distance vector
Details:
Transforms the distance vector (dx,dy) by matrix. This is similar to the cairo:matrix-transform-point function except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows:
tdx = dx * a + dy * c
tdy = dx * b + dy * 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.
See also:
2025-1-18
Function cairo:matrix-transform-point (matrix x y)
Syntax:
(cairo:transform-distance matrix x y) => tx, ty
Arguments:
matrix -- a cairo:matrix-t instance
x -- a number coerced to a double float for the x position
y -- a number coerced to a double float for the y position
tx -- a double float for the transformed x position
ty -- a double float for the transformed y position
Details:
Transforms the point (dx,dy) by matrix.
See also:
2025-1-18

Introduction to Error handling

Cairo uses a single status type to represent all kinds of errors. A status value of :success represents no error and has an integer value of zero. All other status values represent an error.

Cairo's error handling is designed to be easy to use and safe. All major Cairo objects retain an error status internally which can be queried anytime by the users using cairo*-status calls. In the mean time, it is safe to call all Cairo functions normally even if the underlying object is in an error status. This means that no error handling code is required before or after each individual Cairo function call.

Types and functions for Error handling

CEnum cairo:status-t
Declaration:
(cffi:defcenum status-t
  :success
  :no-memory
  :invalid-restore
  :invalid-pop-group
  :no-current-point
  :invalid-matrix
  :invalid-status
  :null-pointer
  :invalid-string
  :invalid-path-data
  :read-error
  :write-error
  :surface-finished
  :surface-type-mismatch
  :pattern-type-mismatch
  :invalid-content
  :invalid-format
  :invalid-visual
  :file-not-found
  :invalid-dash
  :invalid-dsc-comment
  :invalid-index
  :clip-not-representable
  :temp-file-error
  :invalid-stride
  :font-type-mismatch
  :user-font-immutable
  :user-font-error
  :negative-count
  :invalid-clusters
  :invalid-slant
  :invalid-weight
  :invalid-size
  :user-font-not-implemented
  :device-type-mismatch
  :device-error
  :invalid-mesh-construction
  :device-finished
  :jbig2-global-missing
  :png-error
  :freetype-error
  :win32-gdk-error
  :tag-error
  #+cairo-1-18
  :dwrite-error
  #+cairo-1-18
  :svg-font-error
  :last-status)  
Values:
:success
No error has occurred.
:no-memory
Out of memory.
:invalid-restore
The cairo:restore function called without matching the cairo:save function.
:invalid-pop-group
No saved group to pop, that is, the cairo:pop-group function without matching the cairo:push-group function.
:no-current-point
No current point defined.
:invalid-matrix
Invalid matrix (not invertible).
:invalid-status
Invalid cairo:status-t value for an input.
:null-pointer
NULL pointer.
:invalid-string
Input string not valid UTF-8.
:path-data
Input path data not valid.
:read-error
Error while reading from input stream.
:write-error
Error while writing to output stream.
:surface-finished
Target surface has been finished.
:surface-type-mismatch
The surface type is not appropriate for the operation.
:pattern-type-mismatch
The pattern type is not appropriate for the operation.
:invalid-content
Invalid cairo:content-t value for an input.
:invalid-format
Invalid cairo:format-t value for an input.
:invalid-visual
Invalid value for an input Visual.
:file-not-found
File not found.
:invalid-dash
Invalid value for a dash setting.
:invalid-dsc-comment
Invalid value for a DSC comment.
:invalid-index
Invalid index passed to getter.
:clip-not-representable
Clip region not representable in desired format.
:temp-file-error
Error creating or writing to a temporary file.
:invalid-stride
Invalid value for stride.
:font-type-mismatch
The font type is not appropriate for the operation.
:user-font-immutable
The user-font is immutable.
:user-font-error
Error occurred in a user-font callback function.
:negative-count
Negative number used where it is not allowed.
:invalid-clusters
Input clusters do not represent the accompanying text and glyph array.
:invalid-slant
Invalid cairo:font-slant-t value for an input.
:invalid-weight
Invalid cairo:font-weight-t value for an input.
:invalid-size
Invalid value (typically too big) for the size of the input (surface, pattern, etc.).
:user-font-not-implemented
User-font method not implemented.
:device-type-mismatch
The device type is not appropriate for the operation.
:device-error
An operation to the device caused an unspecified error.
:invalid-mesh-construction
A mesh pattern construction operation was used outside of a cairo:mesh-pattern-begin-patch and cairo:mesh-pattern-end-patch pair of functions.
:device-finished
Target device has been finished.
:jbig2-global-missing
CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID has been used on at least one image but no image provided CAIRO_MIME_TYPE_JBIG2_GLOBAL.
:png-error
Error occurred in libpng while reading from or writing to a PNG file.
:freetype-error
Error occurred in libfreetype.
:win32-gdi-error
Error occurred in the Windows Graphics Device Interface.
:tag-error
Invalid tag name, attributes, or nesting.
:dwrite-error
Error occurred in the Windows Direct Write API. Since 1.18
:svg-font-error
Error occurred in OpenType-SVG font rendering. Since 1.18
:last-status
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.
Details:
The cairo:status-t enumeration is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions. but when using a cairo:context-t instance, the last error, if any, is stored in the context and can be retrieved with the cairo:status function.

Use the cairo:status-to-string function to get a human readable representation of an error message.
See also:
2025-1-18
Function cairo:status-to-string (status)
Arguments:
status -- a cairo:status-t value
Returns:
The string representation of the Cario status.
Details:
Provides a human readable description of a Cairo status value.
See also:
2025-1-18

Introduction to Version Information

Cairo provides the ability to examine the version at either compile-time or run-time and in both a human readable form as well as an encoded form suitable for direct comparison. Cairo also provides the cairo:version-encode function to perform the encoding.

Functions for Version Information

Function cairo:version-encode (major minor micro)
Arguments:
major -- an integer for the major component of the version number
minor -- an integer for the minor component of the version number
micro -- an integer for the micro component of the version number
Returns:
The integer with the encoded version.
Details:
This function encodes the given Cairo version into an integer. Two encoded version numbers can be compared as integers. The encoding ensures that later versions compare greater than earlier versions.
See also:
2025-1-18
Function cairo:version ()
Returns:
The integer with the encoded version.
Details:
Returns the version of the Cairo library encoded in a single integer. The encoding ensures that later versions compare greater than earlier versions.

A run-time comparison to check that Cairo's version is greater than or equal to version x.y.z could be performed as follows:
(>= (cairo:version) (cairo:version-encode x y z))  
See also the cairo:version-string function.
See also:
2025-1-18
Function cairo:version-string ()
Returns:
The string containing the Cairo version.
Details:
Returns the version of the Cairo library as a human readable string of the form "x.y.z". See also the cairo:version function.
See also:
2025-1-18

Package graphene

The Graphene library is a thin layer of mathematical types for 3D libraries. The library is implemented for use with the cl-cffi-gtk4 library. This is the API documentation for the Lisp binding to the Graphene library.

Point

CStruct graphene:point-t
Declaration:
(cffi:defcstruct point-t
  (x :float)
  (y :float))  
Slot Access Functions:
Details:
The graphene:point-t structure is a data structure capable of describing a point with two coordinates x and y of type single float.

Access the coordinates with the graphene:point-x and graphene:point-y functions. Use the graphene:with-point and graphene:with-points macros to allocate a new graphene:point-t instance and initialize the point with values.
Examples:
Allocate and initialize a point with values.
(graphene:with-point (p 1.0 1.5)
  (list (graphene:point-x p)
        (graphene:point-y p)))
=> (1.0 1.5)    
See also:
2025-4-1
Accessor graphene:point-x (p)
Syntax:
(graphene:point-x p) => x
(setf (graphene:point-x p) x)
Arguments:
p -- a graphene:point-t instance
x -- a number coerced to a single float for the x coordinate
Details:
Accessor of the x slot of the graphene:point-t structure. The x value is coerced to a single float before assignment.
Examples:
(graphene:with-point (p 0.5 1.0) (graphene:point-x p))
=> 0.5
(graphene:with-point (p) (setf (graphene:point-x p) 3/2))
=> 1.5  
See also:
2025-4-4
Accessor graphene:point-y (p)
Syntax:
(graphene:point-y p) => y
(setf (graphene:point-y p) y)
Arguments:
p -- a graphene:point-t instance
y -- a number coerced to a single float for the y coordinate
Details:
Accessor of the y slot of the graphene:point-t structure. The y value is coerced to a single float before assignment.
Examples:
(graphene:with-point (p 0.5 1.0) (graphene:point-y p))
=> 1.0
(graphene:with-point (p) (setf (graphene:point-y p) 3/2))
=> 1.5  
See also:
2025-4-4
Macro graphene:with-point ((var &rest args) &body body)
Syntax:
(graphene:with-point (p) body) => result
(graphene:with-point (p p1) body) => result
(graphene:with-point (p (v graphene:vec2-t)) body) => result
(graphene:with-point (p x y) body) => result
Arguments:
p -- a graphene:point-t instance to create and initialize
p1 -- a graphene:point-t instance to use for initialization
v -- a graphene:vec2-t instance to use for initialization
x -- a number coerced to a single float for the x component
y -- a number coerced to a single float for the y component
Details:
The graphene:with-point macro allocates a new graphene:point-t instance, initializes the point with the given values and executes the body that uses the point. After execution of the body the allocated memory for the point is released.

When no argument is given the components of the point are initialized to zero. The initialization with two single floats uses the graphene:point-init function. The initialization from another point is done with the graphene:point-init-from-point function. That is the default when no type specifier for the value is given. If the value has the type specifier graphene:vec2-t the point is initialized with the graphene:point-init-from-vec2 function.
Notes:
The memory is allocated with the graphene:point-alloc function and released with the graphene:point-free function.
Examples:
Initialize a point with no value and two single floats.
(graphene:with-point (p)
  (list (graphene:point-x p) (graphene:point-y p)))
=> (0.0 0.0)
(graphene:with-point (p 1.5 1.7)
  (list (graphene:point-x p) (graphene:point-y p)))
=> (1.5 1.7)    
Use a vector for initialization of the point.
(graphene:with-vec2 (v 3.5 4.5)
  (graphene:with-point (p (v graphene:vec2-t))
    (list (graphene:point-x p) (graphene:point-y p))))
=> (3.5 4.5)    
See also:
2025-4-2
Macro graphene:with-points (vars &body body)
Syntax:
(graphene:with-points (p1 p2 p3 ... pn) body) => result
Arguments:
p1 ... pn -- newly created graphene:point-t instances
body -- a body that uses the bindings p1 ... pn
Details:
The graphene:with-points macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each point can be initialized with values using the syntax for the graphene:with-point macro. See also the graphene:with-point documentation.
Examples:
(graphene:with-points (p1 (p2 1.2 1.3) (p3 p2))
  (list (list (graphene:point-x p1) (graphene:point-y p1))
        (list (graphene:point-x p2) (graphene:point-y p2))
        (list (graphene:point-x p3) (graphene:point-y p3))))
=> ((0.0 0.0) (1.2 1.3) (1.2 1.3))    
See also:
2025-4-1
Function graphene:point-alloc ()
Returns:
The newly allocated graphene:point-t instance.
Details:
Allocates a new graphene:point-t instance. The coordinates of the returned point are initialized to (0.0, 0.0). Use the graphene:point-free function to free the resources allocated by this function.
Examples:
It is possible to chain this function with the graphene:point-init or graphene:point-init-from-point functions.
(defun point-new (x y)
  (graphene:point-init (graphene:point-alloc) x y))
(defun point-copy (p)
  (graphene:point-init-from-point (graphene:point-alloc) p))    
See also:
2025-4-1
Function graphene:point-free (p)
Arguments:
p -- a graphene:point-t instance
Details:
Frees the resources allocated by the graphene:point-alloc function.
See also:
2025-4-1
Function graphene:point-zero ()
Returns:
The graphene:point-t instance with a zero point.
Details:
Returns a point with the two coordinates set to zero.
Examples:
(values (graphene:point-x (graphene:point-zero))
        (graphene:point-y (graphene:point-zero)))
=> 0.0
=> 0.0    
See also:
2025-4-1
Function graphene:point-init (p x y)
Arguments:
p -- a graphene:point-t instance
x -- a number coerced to a single float for the x coordinate
y -- a number coerced to a single float for the y coordinate
Returns:
The initialized graphene:point-t instance.
Details:
Initializes the point to the given x and y coordinates. It is safe to call this function multiple times.
See also:
2025-4-1
Function graphene:point-init-from-point (p src)
Arguments:
p -- a graphene:point-t instance
src -- a graphene:point-t instance to use
Returns:
The initialized graphene:point-t instance.
Details:
Initializes the point using the coordinates of src.
See also:
2025-4-1
Function graphene:point-init-from-vec2 (p v)
Arguments:
p -- a graphene:point-t instance
v -- a graphene:vec2-t instance to use
Returns:
The initialized graphene:point-t instance.
Details:
Initializes the point using the components of the given vector.
See also:
2025-4-1
Function graphene:point-to-vec2 (p v)
Arguments:
p -- a graphene:point-t instance
v -- a graphene:vec2-t instance
Returns:
The graphene:vec2-t instance with the coordinates of the point.
Details:
Stores the coordinates of the given point into a vector.
Examples:
(graphene:with-point (p 1.0 2.0)
  (graphene:with-vec2 (v)
    (graphene:vec2-to-float (graphene:point-to-vec2 p v))))
=> (1.0 2.0)    
See also:
2025-4-1
Function graphene:point-equal (a b)
Arguments:
a -- a graphene:point-t instance
b -- a graphene:point-t instance
Returns:
True, if the points have the same coordinates, otherwise false.
Details:
Checks whether two given points are equal. This function accounts for floating point fluctuations. If you want to control the fuzziness of the match, you can use the graphene:point-near function instead.
See also:
2025-4-1
Function graphene:point-near (a b epsilon)
Arguments:
a -- a graphene:point-t instance
b -- a graphene:point-t instance
epsilon -- a number coerced to a single float with the threshold between the two points
Returns:
True, if the distance between the points is within epsilon.
Details:
Checks whether the two points a and b are within the threshold of epsilon equal.
See also:
2025-4-1
Function graphene:point-distance (a b)
Syntax:
(graphene:point-distance a b) => dist, dx, dy
Arguments:
a -- a graphene:point-t instance
b -- a graphene:point-t instance
dist -- a single float for the distance between the two points
dx -- a single float for the distance component of the X axis
dy -- a single float for the distance component of the Y axis
Details:
Computes the distance between the two given points.
Examples:
(graphene:with-points ((a 0 0) (b 1 1))
  (graphene:point-distance a b))
=> 1.4142135
=> 1.0
=> 1.0    
See also:
2025-4-1
Function graphene:point-interpolate (a b factor result)
Arguments:
a -- a graphene:point-t instance
b -- a graphene:point-t instance
factor -- a number coerced to a double float for the linear interpolation factor
result -- a graphene:point-t instance for the interpolated point
Returns:
The graphene:point-t instance with the interpolated point.
Details:
Linearly interpolates the coordinates of a and b using the given factor.
Examples:
(graphene:with-points ((a 0 0) (b 1 2) result)
  (graphene:point-interpolate a b 0.5 result)
  (values (graphene:point-x result) (graphene:point-y result)))
=> 0.5
=> 1.0    
See also:
2025-4-1

Point3D

CStruct graphene:point3d-t
Declaration:
(cffi:defcstruct point3d-t
  (x :float)
  (y :float)
  (z :float))  
Slot Access Functions:
Details:
The graphene:point3d-t structure is a data structure capable of describing a point with three coordinates.

Access the coordinates with the graphene:point3d-x, graphene:point3d-y and graphene:point3d-z functions. Use the graphene:with-point3d and graphene:with-point3ds macros to allocate a new graphene:point3d-t instance and initialize the point with values.
Examples:
Allocate and initalize a point with values.
(graphene:with-point3d (p 1.0 1/2 5)
  (list (graphene:point3d-x p)
        (graphene:point3d-y p)
        (graphene:point3d-z p)))
=> (1.0 0.5 5.0)    
See also:
2025-4-2
Accessor graphene:point3d-x (p)
Syntax:
(graphene:point3d-x p) => x
(setf (graphene:point3d-x p) x)
Arguments:
p -- a graphene:point3d-t instance
x -- a number coerced to a single float for the x coordinate
Details:
Accessor of the x slot of the graphene:point3d-t structure. The x value is coerced to a single float before assignment.
Examples:
(graphene:with-point3d (p 0.5 1.0 1.5)
  (list (graphene:point3d-x p) (graphene:point3d-y p) (graphene:point3d-z p)))
=> (0.5 1.0 1.5)
(graphene:with-point3d (p)
  (setf (graphene:point3d-x p) 2.0
        (graphene:point3d-y p) 2.5
        (graphene:point3d-z p) 3.0)
  (list (graphene:point3d-x p) (graphene:point3d-y p) (graphene:point3d-z p)))
=> (2.0 2.5 3.0)    
See also:
2025-4-2
Accessor graphene:point3d-y (p)
Syntax:
(graphene:point3d-y p) => y
(setf (graphene:point3d-y p) y)
Arguments:
point -- a graphene:point3d-t instance
x -- a number coerced to a single float for the y coordinate
Details:
Accessor of the y slot of the graphene:point3d-t structure. The y value is coerced to a single float before assignment. See the graphene:point3d-x documentation for an example.
See also:
2025-4-2
Accessor graphene:point3d-z (p)
Syntax:
(graphene:point3d-z p) => z
(setf (graphene:point3d-z p) z)
Arguments:
p -- a graphene:point3d-t instance
x -- a number coerced to a single float for the z coordinate
Details:
Accessor of the z slot of the graphene:point3d-t structure. The z value is coerced to a single float before assignment. See the graphene:point3d-x documentation for an example.
See also:
2025-4-2
Macro graphene:with-point3d ((var &rest args) &body body)
Syntax:
(graphene:with-point3d (p) body) => result
(graphene:with-point3d (p p1) body) => result
(graphene:with-point3d (p (v graphene:vec3-t)) body) => result
(graphene:with-point3d (p x y z) body) => result
Arguments:
p -- a graphene:point3d-t instance to create and initialize
p1 -- a graphene:point3d-t instance to use for initialization
v -- a graphene:vec3-t instance to use for initialization
x -- a number coerced to a single float for the x component
y -- a number coerced to a single float for the y component
z -- a number coerced to a single float for the z component
Details:
The graphene:with-point3d macro allocates a new graphene:point3d-t instance, initializes the point with the given values and executes the body that uses the point. After execution of the body the allocated memory for the point is released.

When no argument is given the components of the point are initialized to zero. The initialization with three single floats uses the graphene:point3d-init function. The initialization from another point is done with the graphene:point3d-init-from-point function. That is the default when no type specifier for the value is given. If the value has the type specifier graphene:vec3-t the point is initialized with the graphene:point3d-init-from-vec3 function.
Notes:
The memory is allocated with the graphene:point3d-alloc function and released with the graphene:point3d-free function.
Examples:
Initialize a point with no value and three single floats.
(graphene:with-point3d (p)
  (list (graphene:point3d-x p) (graphene:point3d-y p) (graphene:point3d-z p)))
=> (0.0 0.0 0.0)
(graphene:with-point3d (p 1.5 1.7 1.9)
  (list (graphene:point3d-x p) (graphene:point3d-y p) (graphene:point3d-z p)))
=> (1.5 1.7 1.9)    
Use a vector for initialization of the point.
(graphene:with-vec3 (v 3.5 4.5 5.5)
  (graphene:with-point3d (p (v graphene:vec3-t))
    (list (graphene:point3d-x p)
          (graphene:point3d-y p)
          (graphene:point3d-z p))))
=> (3.5 4.5 5.5)    
This examples uses the graphene:with-point3ds macro to initialize two points. The second point is intialized with the values from the first point.
(graphene:with-point3ds ((p1 0.3 0.5 0.7) (p2 p1))
  (list (graphene:point3d-x p2)
        (graphene:point3d-y p2)
        (graphene:point3d-z p2)))
=> (0.3 0.5 0.7)    
See also:
2025-4-2
Macro graphene:with-point3ds (vars &body body)
Syntax:
(graphene:with-point3ds (p1 p2 p3 ... pn) body) => result
Arguments:
p1 ... pn -- newly created graphene:point3d-t instances
body -- a body that uses the bindings p1 ... pn
Details:
The graphene:with-point3ds macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each point can be initialized with values using the syntax for the graphene:with-point3d macro. See also the graphene:with-point3d documentation.
Examples:
(graphene:with-point3ds (p1 (p2 1.2 1.3 1.4) (p3 p2))
  (list (list (graphene:point3d-x p1)
              (graphene:point3d-y p1)
              (graphene:point3d-z p1))
        (list (graphene:point3d-x p2)
              (graphene:point3d-y p2)
              (graphene:point3d-z p2))
        (list (graphene:point3d-x p3)
              (graphene:point3d-y p3)
              (graphene:point3d-z p3))))
=> ((0.0 0.0 0.0) (1.2 1.3 1.4) (1.2 1.3 1.4))    
See also:
2025-4-2
Function graphene:point3d-alloc ()
Returns:
The newly allocated graphene:point3d-t instance.
Details:
Allocates a new graphene:point3d-t instance. The coordinates of the returned point are initialized to (0.0, 0.0, 0.0). Use the graphene:point3d-free function to free the resources allocated by this function.
Examples:
It is possible to chain this function with the graphene:point3d-init or graphene:point3d-init-from-point functions.
(defun point3d-new (x y z)
  (graphene:point3d-init (graphene:point3d-alloc) x y z))
(defun point3d-copy (p)
  (graphene:point3d-init-from-point (graphene:point3d-alloc) p))    
See also:
2025-4-2
Function graphene:point3d-free (p)
Arguments:
p -- a graphene:point3d-t instance
Details:
Frees the resources allocated by the graphene:point3d-alloc function.
See also:
2025-4-2
Function graphene:point3d-zero ()
Returns:
The graphene:point3d-t instance with a zero point.
Details:
Returns a point with all three coordinates set to zero.
Examples:
(values (graphene:point3d-x (graphene:point3d-zero))
        (graphene:point3d-y (graphene:point3d-zero))
        (graphene:point3d-z (graphene:point3d-zero)))
=> 0.0
=> 0.0
=> 0.0    
See also:
2025-4-2
Function graphene:point3d-init (p x y z)
Arguments:
p -- a graphene:point3d-t instance
x -- a number coerced to a single float for the x coordinate
y -- a number coerced to a single float for the y coordinate
z -- a number coerced to a single float for the z coordinate
Returns:
The initialized graphene:point3d-t instance.
Details:
Initializes the point to the given x, y, and z coordinates. It is safe to call this function multiple times.
See also:
2025-4-2
Function graphene:point3d-init-from-point (p src)
Arguments:
p -- a graphene:point3d-t instance
src -- a graphene:point3d-t instance to use
Returns:
The initialized graphene:point3d-t instance.
Details:
Initializes the point using the coordinates of src.
See also:
2025-4-2
Function graphene:point3d-init-from-vec3 (p v)
Arguments:
p -- a graphene:point3d-t instance
v -- a graphene:vec3-t instance to use
Returns:
The initialized graphene:point3d-t instance.
Details:
Initializes the point using the components of the given vector.
See also:
2025-4-2
Function graphene:point3d-to-vec3 (p v)
Arguments:
p -- a graphene:point3d-t instance
v -- a graphene:vec3-t instance
Returns:
The graphene:vec3-t instance with the coordinates of the point.
Details:
Stores the coordinates of the given point into a vector.
Examples:
(graphene:with-point3d (p 1.0 2.0 3.0)
  (graphene:with-vec3 (v)
    (graphene:vec3-to-float (graphene:point3d-to-vec3 p v))))
=> (1.0 2.0 3.0)    
See also:
2025-4-2
Function graphene:point3d-equal (a b)
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
Returns:
True, if the points have the same coordinates, otherwise false.
Details:
Checks whether two given points are equal. This function accounts for floating point fluctuations. If you want to control the fuzziness of the match, you can use the graphene:point3d-near function instead.
See also:
2025-4-2
Function graphene:point3d-near (a b epsilon)
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
epsilon -- a number coerced to a single float with the threshold between the two points
Returns:
True, if the distance between the points is within epsilon, otherwise false.
Details:
Checks whether the two points a and b are within the threshold of epsilon equal.
See also:
2025-4-2
Function graphene:point3d-distance (a b delta)
Syntax:
(graphene:point-distance a b) => dist, delta
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
delta -- a graphene:vec3-t instance for the calculated distance components on the X, Y, and Z axis
dist -- a single float for the distance between two points
Details:
Computes the distance between the two given points.
Examples:
(graphene:with-vec3 (v)
  (graphene:with-point3ds ((p1 0 0 0) (p2 1 1 1))
    (multiple-value-bind (dist delta)
        (graphene:point3d-distance p1 p2 v)
      (values dist
              (graphene:vec3-to-float delta)))))
=> 1.7320508
=> (1.0 1.0 1.0)    
See also:
2025-4-2
Function graphene:point3d-interpolate (a b factor result)
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
factor -- a number coerced to a double float for the linear interpolation factor
result -- a graphene:point3d-t instance for the interpolated point
Returns:
The graphene:point3d-t instance with the interpolated point.
Details:
Linearly interpolates the coordinates of a and b using the given factor.
Examples:
(graphene:with-point3ds ((a 0 0 0) (b 1 2 3) result)
  (graphene:point3d-interpolate a b 0.5 result)
  (values (graphene:point3d-x result)
          (graphene:point3d-y result)
          (graphene:point3d-z result)))
=> 0.5
=> 1.0
=> 1.5    
See also:
2025-4-2
Function graphene:point3d-scale (p factor result)
Arguments:
p -- a graphene:point3d-t instance
factor -- a number coerced to a single float for the scaling factor
result -- a graphene:point3d-t instance for the scaled point
Returns:
The graphene:point3d-t instance with the scaled point.
Details:
Scales the coordinates of the given point by the given factor.
See also:
2025-4-2
Function graphene:point3d-cross (a b result)
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
result -- a graphene:point3d-t instance for the cross product
Returns:
The graphene:point3d-t instance with the cross product.
Details:
Computes the cross product of the two given points.
See also:
2025-4-2
Function graphene:point3d-dot (a b)
Arguments:
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
Returns:
The single float with the value of the dot product.
Details:
Computes the dot product of the two given points.
See also:
2025-4-2
Function graphene:point3d-length (p)
Arguments:
p -- a graphene:point3d-t instance
Returns:
The single float with the value of the length of the vector represented by the point.
Details:
Computes the length of the vector represented by the coordinates of the given point.
See also:
2025-4-2
Function graphene:point3d-normalize (p result)
Arguments:
point -- a graphene:point3d-t instance
result -- a graphene:point3d-t instance
Returns:
The graphene:point3d-t instance with the normalized point.
Details:
Computes the normalization of the vector represented by the coordinates of the given point.
See also:
2025-4-2
Function graphene:point3d-normalize-viewport (p viewport znear zfar result)
Arguments:
p -- a graphene:point3d-t instance
viewport -- a graphene:rect-t instance representing a viewport
znear -- a number coerced to a single float for the coordinate of the near clipping plane, or 0.0 for the default near clipping plane
zfar -- a number coerced to a single float for the coordinate of the far clipping plane, or 1.0 for the default far clipping plane
result -- a graphene:point3d-t instance for the nomalized point
Returns:
The graphene:point3d-t instance with the normalized point.
Details:
Normalizes the coordinates of the point using the given viewport and clipping planes. The coordinates of the resulting point will be in the [-1.0, 1.0] range.
See also:
2025-4-2

Size

CStruct graphene:size-t
Declaration:
(cffi:defcstruct size-t
  (width :float)
  (height :float))  
Slot Access Functions:
Details:
The graphene:size-t structure is a data structure capable of describing a size with two components width and height of type float.

Access the coordinates with the graphene:size-width and graphene:size-height functions. Use the graphene:with-size and graphene:with-sizes macros to allocate a new graphene:size-t instance and initialize the size with values.
See also:
2025-4-3
Accessor graphene:size-width (size)
Syntax:
(graphene:size-width size) => width
(setf (graphene:size-width size) width)
Arguments:
size -- a graphene:size-t instance
width -- a number coerced to a single float for the width component
Details:
Accessor of the width slot of the graphene:size-t structure.
See also:
2025-4-3
Accessor graphene:size-height (size)
Syntax:
(graphene:size-height size) => height
(setf (graphene:size-height size) height)
Arguments:
size -- a graphene:size-t instance
width -- a number coerced to a single float for the height component
Details:
Accessor of the height slot of the graphene:size-t structure.
See also:
2025-4-3
Macro graphene:with-size ((var &rest args) &body body)
Syntax:
(graphene:with-size (s) body) => result
(graphene:with-size (s s1) body) => result
(graphene:with-size (s width height) body) => result
Arguments:
s -- a graphene:size-t instance to create and initialize
s1 -- a graphene:size-t instance to use for initialization
width -- a number coerced to a single float for the width component
height -- a number coerced to a single float for the height component
Details:
The graphene:with-size macro allocates a new graphene:size-t instance, initializes the graphene:size-t instance with the given values and executes the body that uses the size. After execution of the body the allocated memory for the size is released.

When no argument is given the components of the graphene:size-t instance are initialized to zero. The initialization with two single floats uses the graphene:size-init function. The initialization from another size is done with the graphene:size-init-from-size function.
Notes:
The memory is allocated with the graphene:size-alloc function and released with the graphene:size-free function.
Examples:
Initialize a graphene:size-t instance with no value and two float values.
(graphene:with-size (s)
  (list (graphene:size-width s) (graphene:size-height s)))
=> (0.0 0.0)
(graphene:with-size (s 1.5 1.7)
  (list (graphene:size-width s) (graphene:size-height s)))
=> (1.5 1.7)    
This examples uses the graphene:with-sizes macro to initialize two graphene:size-t instances. The second instance is intialized with the values from the first instance.
(graphene:with-sizes ((s1 0.3 0.5) (s2 s1))
  (list (graphene:size-width s2) (graphene:size-height s2)))
=> (0.3 0.5)    
See also:
2025-4-3
Macro graphene:with-sizes (vars &body body)
Syntax:
(graphene:with-sizes (s1 s2 s3 ... sn) body) => result
Arguments:
s1 ... sn -- newly created graphene:size-t instances
body -- a body that uses the bindings s1 ... sn
Details:
The graphene:with-sizes macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each size can be initialized with values using the syntax for the graphene:with-size macro. See also the graphene:with-size documentation.
Examples:
(graphene:with-sizes (s1 (s2 1.2 1.3) (s3 s2))
  (list (list (graphene:size-width s1) (graphene:size-height s1))
        (list (graphene:size-width s2) (graphene:size-height s2))
        (list (graphene:size-width s3) (graphene:size-height s3))))
=> ((0.0 0.0) (1.2 1.3) (1.2 1.3))    
See also:
2025-4-3
Function graphene:size-alloc ()
Returns:
The newly allocated graphene:size-t instance.
Details:
Allocates a new graphene:size-t instance. The components of the returned graphene:size-t instance are initialized to zero. Use the graphene:size-free function to free the resources allocated by this function.
See also:
2025-4-3
Function graphene:size-free (size)
Arguments:
size -- a graphene:size-t instance
Details:
Frees the resources allocated by the graphene:size-alloc function.
See also:
2025-4-3
Function graphene:size-zero ()
Returns:
The graphene:size-t instance with a zero size.
Details:
Returns a graphene:size-t instance with the two components set to zero.
Examples:
(values (graphene:size-width (graphene:size-zero))
        (graphene:size-height (graphene:size-zero)))
=> 0.0
=> 0.0    
See also:
2025-4-3
Function graphene:size-init (size width height)
Arguments:
size -- a graphene:size-t instance
width -- a number coerced to a single float for the width component
height -- a number coerced to a single float for the height component
Returns:
The initialized graphene:size-t instance.
Details:
Initializes the graphene:size-t instance to the given width and height values. It is safe to call this function multiple times.
See also:
2025-4-3
Function graphene:size-init-from-size (size source)
Arguments:
size -- a graphene:size-t instance
source -- a graphene:size-t instance to use
Returns:
The initialized graphene:size-t instance.
Details:
Initializes the graphene:size-t instance using the values of source.
See also:
2025-4-3
Function graphene:size-equal (a b)
Arguments:
a -- a graphene:size-t instance
b -- a graphene:size-t instance
Returns:
True, if the graphene:size-t instances have the same components, otherwise false.
Details:
Checks whether two given graphene:size-t instances are equal.
See also:
2025-4-3
Function graphene:size-interpolate (a b factor result)
Arguments:
a -- a graphene:size-t instance
b -- a graphene:size-t instance
factor -- a number coerced to a double float for the linear interpolation factor
result -- a graphene:size-t instance for the interpolated size
Returns:
The graphene:size-t instance with the interpolated size.
Details:
Linearly interpolates the components of a and b using the given factor.
See also:
2025-4-3
Function graphene:size-scale (size factor result)
Arguments:
size -- a graphene:size-t instance
factor -- a number coerced to a single float for the scaling factor
result -- a graphene:size-t instance for the scaled size
Returns:
The graphene:size-t instance with the scaled size.
Details:
Scales the components of the given graphene:size-t instance by the given factor.
See also:
2025-4-3

Rectangle

CStruct graphene:rect-t
Declaration:
(cffi:defcstruct rect-t
  (origin (:struct point-t))
  (size (:struct size-t)))  
Values:
origin
The graphene:point-t instance for the coordinates for the origin of the rectangle.
size
The graphene:size-t instance for the size of the rectangle.
Slot Access Functions:
Details:
The location and size of a rectangle region. The width and height of a graphene:rect-t instance can be negative. For instance, a graphene:rect-t instance with an origin of (0,0) and a size of (10,10) is equivalent to a graphene:rect-t instance with an origin of (10,10) and a size of (-10,-10).

Application code can normalize rectangles using the graphene:rect-normalize function. This function will ensure that the width and height of a rectangle are positive values. All functions taking a graphene:rect-t instance as an argument will internally operate on a normalized copy. All functions returning a graphene:rect-t instance will always return a normalized rectangle.
Examples:
A rectangle with a negative size is normalized internally:
(graphene:with-rect (rect 10 10 -10 -10)
  (list (graphene:rect-x rect)
        (graphene:rect-y rect)
        (graphene:rect-width rect)
        (graphene:rect-height rect)))
=> (0.0 0.0 10.0 10.0)    
See also:
2025-3-8
Macro graphene:with-rect ((var &rest args) &body body)
Syntax:
(graphene:with-rect (rect) body) => result
(graphene:with-rect (rect src) body) => result
(graphene:with-rect (rect x y width height) body) => result
Arguments:
rect -- a graphene:rect-t instance to create and initialize
src -- a graphene:rect-t instance to use for initialization
x -- a number coerced to a single float for the x coordinate
y -- a number coerced to a single float for the y coordinate
width -- a number coerced to a single float for the width
height -- a number coerced to a single float for the height
Details:
The graphene:with-rect macro allocates a new graphene:rect-t instance, initializes the rectangle with the given values and executes the body that uses the rectangle. After execution of the body the allocated memory for the rectangle is released.

When no argument is given the components of the rectangle are initialized to zero. The initialization with four single floats uses the graphene:rect-init function. The initialization from another rectangle is done with the graphene:rect-init-from-rect function.
Notes:
The memory is allocated with the graphene:rect-alloc function and released with the graphene:rect-free function.
See also:
2025-4-3
Macro graphene:with-rects (vars &body body)
Syntax:
(graphene:with-rects (rect1 rect2 ... rectn) body) => result
Arguments:
rect1 ... rectn -- newly created graphene:rect-t instances
body -- a body that uses the bindings rect1 ... rectn
Details:
The graphene:with-rects macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each rectangle can be initialized with values using the syntax for the graphene:with-rect macro. See also the graphene:with-rect documentation.
See also:
2025-3-8
Accessor graphene:rect-origin (rect)
Syntax:
(graphene:rect-origin rect) => origin
(setf (graphene:rect-origin rect) origin)
Arguments:
rect -- a graphene:rect-t instance
origin -- a graphene:point-t instance for the origin of the rectangle
Details:
Accessor of the origin slot of the graphene:rect-t structure.
See also:
2025-3-8
Accessor graphene:rect-size (rect)
Syntax:
(graphene:rect-size rect) => size
(setf (graphene:rect-size rect) size)
Arguments:
rect -- a graphene:rect-t instance
size -- a graphene:size-t instance for the size of the rectangle
Details:
Accessor of the size slot of the graphene:rect-t structure.
See also:
2025-3-8
Function graphene:rect-alloc ()
Returns:
The new graphene:rect-t instance.
Details:
Allocates a new graphene:rect-t instance. The contents of the returned rectangle are undefined.
See also:
2025-3-8
Function graphene:rect-free (rect)
Arguments:
rect -- a graphene:rect-t instance
Details:
Frees the resources allocated by the graphene:rect-alloc function.
See also:
2025-3-8
Function graphene:rect-init (rect x y width height)
Arguments:
rect -- a graphene:rect-t instance
x -- a number coerced to a single float for the x coordinate
y -- a number coerced to a single float for the y coordinate
width -- a number coerced to a single float for the width
height -- a number coerced to a single float for the height
Returns:
The initialized graphene:rect-t instance.
Details:
Initializes the given rectangle with the given values. This function will implicitly normalize the rectangle before returning.
See also:
2025-4-3
Function graphene:rect-init-from-rect (rect src)
Arguments:
rect -- a graphene:rect-t instance
src -- a graphene:rect-t instance
Returns:
The initialized graphene:rect-t instance.
Details:
Initializes rect using the given src rectangle. This function will implicitly normalize the rectangle before returning.
See also:
2025-3-8
Function graphene:rect-equal (a b)
Arguments:
a -- a graphene:rect-t instance
b -- a graphene:rect-t instance
Returns:
True if the rectangles are equal.
Details:
Checks whether the two given rectangle are equal.
See also:
2025-3-8
Function graphene:rect-normalize (rect result)
Arguments:
rect -- a graphene:rect-t instance
result -- a graphene:rect-t instance for the result
Returns:
The normalized graphene:rect-t instance.
Details:
Normalizes the passed rectangle. This function ensures that the size of the rectangle is made of positive values, and that the origin is the top-left corner of the rectangle.
See also:
2025-3-8
Function graphene:rect-center (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
The graphene:point-t instance.
Details:
Retrieves the coordinates of the center of the given rectangle.
Examples:
(graphene:with-rect (rect 0 0 10 20)
  (graphene:with-point (point)
    (graphene:rect-center rect point)
    (values (graphene:point-x point)
            (graphene:point-y point))))
=> 5.0
=> 10.0    
See also:
2025-3-8
Function graphene:rect-top-left (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
The graphene:point-t instance
Details:
Retrieves the coordinates of the top-left corner of the given rectangle.
See also:
2025-3-8
Function graphene:rect-top-right (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
The graphene:point-t instance
Details:
Retrieves the coordinates of the top-right corner of the given rectangle.
See also:
2025-3-8
Function graphene:rect-bottom-right (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
The graphene:point-t instance
Details:
Retrieves the coordinates of the bottom-right corner of the given rectangle.
See also:
2025-3-8
Function graphene:rect-bottom-left (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
The graphene:point-t instance
Details:
Retrieves the coordinates of the bottom-left corner of the given rectangle.
See also:
2025-3-8
Function graphene:rect-x (rect)
Arguments:
rect -- a graphene:rect-t instance
Returns:
The single float with the normalized x coordinate of the rectangle.
Details:
Retrieves the normalized x coordinate of the origin of the given rectangle.
See also:
2025-3-8
Function graphene:rect-y (rect)
Arguments:
rect -- a graphene:rect-t instance
Returns:
The single float with the normalized y coordinate of the rectangle.
Details:
Retrieves the normalized y coordinate of the origin of the given rectangle.
See also:
2025-3-8
Function graphene:rect-width (rect)
Arguments:
rect -- a graphene:rect-t instance
Returns:
The single float with the normalized width of the rectangle.
Details:
Retrieves the normalized width of the given rectangle.
See also:
2025-3-8
Function graphene:rect-height (rect)
Arguments:
rect -- a graphene:rect-t instance
Returns:
The single float with the normalized height of the rectangle.
Details:
Retrieves the normalized height of the given rectangle.
See also:
2025-3-8
Function graphene:rect-area (rect)
Arguments:
rect -- a graphene:rect-t instance
Returns:
The single float with the area of the given normalized rectangle.
Details:
Compute the area of the given normalized rectangle.
Examples:
(graphene:with-rect (rect 0 0 2 3)
  (graphene:rect-area rect))
=> 6.0    
See also:
2025-3-8
Function graphene:rect-vertices (rect vertices)
Arguments:
rect -- a graphene:rect-t instance
vertices -- a list with 4 graphene:vec2-t instances
Returns:
The list with 4 graphene:vec2-t instances.
Details:
Computes the four vertices of a rectangle.
Examples:
(graphene:with-rect (rect 0 0 2 4)
  (graphene:with-vec2s (v1 v2 v3 v4)
    (mapcar #'graphene:vec2-to-float
            (graphene:rect-vertices rect (list v1 v2 v3 v4)))))
=> ((0.0 0.0) (2.0 0.0) (2.0 4.0) (0.0 4.0))    
See also:
2025-3-8
Function graphene:rect-union (a b result)
Arguments:
a -- a graphene:rect-t instance
b -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the result.
Details:
Computes the union of the two given rectangles.
See also:
2025-3-8
Function graphene:rect-intersection (a b result)
Arguments:
a -- a graphene:rect-t instance
b -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the result, or nil if the rectangles do not intersect.
Details:
Computes the intersection of the two given rectangles. If the two rectangles do not intersect, result will contain a degenerate rectangle with origin in (0, 0) and a size of 0.
See also:
2025-3-8
Function graphene:rect-contains-point (rect point)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
Returns:
True if the rectangle contains the point.
Details:
Checks whether a rectangle contains the given coordinates.
See also:
2025-3-8
Function graphene:rect-contains-rect (a b)
Arguments:
a -- a graphene:rect-t instance
b -- a graphene:rect-t instance
Returns:
True if the rectangle a fully contains b.
Details:
Checks whether a rectangle contains the given rectangle.
See also:
2025-3-8
Function graphene:rect-offset (rect dx dy result)
Arguments:
rect -- a graphene:rect-t instance
dx -- a number coerced to a single float for the horizontal offset
dy -- a number coerced to a single float for the vertical offset
result -- a graphene:rect-t instance for the result
Returns:
The graphene:rect-t instance with the offset rectangle.
Details:
Offsets the origin of the rectangle by dx and dy. The size of the rectangle is unchanged.
See also:
2025-3-8
Function graphene:rect-inset (rect dx dy result)
Arguments:
rect -- a graphene:rect-t instance
dx -- a number coerced to a single float for the horizontal inset
dy -- a number coerced to a single float for the vertical inset
result -- a graphene:rect-t instance for the result
Returns:
The graphene:rect-t instance with the inset rectangle.
Details:
Changes the given rectangle to be smaller, or larger depending on the given inset parameters. To create an inset rectangle, use positive dx or dy values. To create a larger, encompassing rectangle, use negative dx or dy values.

The origin of the rectangle is offset by dx and dy, while the size is adjusted by (2 * dx, 2 * dy). If dx and dy are positive values, the size of the rectangle is decreased. If dx and dy are negative values, the size of the rectangle is increased.

If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero.
See also:
2025-3-8
Function graphene:rect-round-extents (rect result)
Arguments:
rect -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance for the rectangle with rounded extents.
Details:
Rounds the origin of the given rectangle to its nearest integers recompute the size so that the rectangle is large enough to contain all the corners of the original rectangle.

This function is the equivalent of calling floor on the coordinates of the origin, and recomputing the size calling ceil on the bottom-right coordinates.

If you want to be sure that the rounded rectangle completely covers the area that was covered by the original rectangle - that is, you want to cover the area including all its corners - this function will make sure that the size is recomputed taking into account the ceiling of the coordinates of the bottom-right corner. If the difference between the original coordinates and the coordinates of the rounded rectangle is greater than the difference between the original size and and the rounded size, then the move of the origin would not be compensated by a move in the anti-origin, leaving the corners of the original rectangle outside the rounded one.
See also:
2025-3-8
Function graphene:rect-expand (rect point result)
Arguments:
rect -- a graphene:rect-t instance
point -- a graphene:point-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the expanded rectangle.
Details:
Expands a rectangle to contain the given point.
See also:
2025-3-8
Function graphene:rect-interpolate (a b factor result)
Arguments:
a -- a graphene:rect-t instance
b -- a graphene:rect-t instance
factor -- a number coerced to a double float for the linear interpolation factor
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the interpolated rectangle.
Details:
Linearly interpolates the origin and size of the two given rectangles.
See also:
2025-3-8
Function graphene:rect-zero ()
Returns:
The fixed graphene:rect-t instance.
Details:
Returns a degenerate rectangle with origin fixed at (0,0) and a size of (0,0).
See also:
2025-3-8
Function graphene:rect-scale (rect sh sv result)
Arguments:
rect -- a graphene:rect-t instance
sh -- a number coerced to a single float for the horizontal scale factor
sv -- a number coerced to a single float for the vertical scale factor
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the scaled rectangle.
Details:
Scales the size and origin of a rectangle horizontaly by sh, and vertically by sv. The returned rectangle is normalized.
See also:
2025-3-8

Quad

CStruct graphene:quad-t
Declaration:
(cffi:defcstruct quad-t)  
Details:
A 4 vertex quadrilateral, as represented by four graphene:point-t instances.
See also:
2025-4-3
Macro graphene:with-quad ((var &rest args) &body body)
Syntax:
(graphene:with-quad (q) body) => result
(graphene:with-quad (q r) body) => result
(graphene:with-quad (q p0 p1 p2 p3) body) => result
Arguments:
q -- a graphene:quad-t instance to create and initialize
r -- a graphene:rect-t instance
p0 -- a graphene:point-t instance for the first point
p1 -- a graphene:point-t instance for the second point
p2 -- a graphene:point-t instance for the third point
p3 -- a graphene:point-t instance for the fourth point
Details:
The graphene:with-quad macro allocates a new graphene:quad-t instance, initializes the quadrilateral with the given values and executes the body that uses the quadrilateral. After execution of the body the allocated memory for the quadrilateral is released.

When no argument is given the components of the quadrilateral are initialized to zeros. The initialization with four points uses the graphene:quad-init function. The initialization from a rectangle is done with the graphene:quad-init-from-rect function.
Notes:
The memory is allocated with the graphene:quad-alloc function and released with the graphene:quad-free function.
See also:
2025-4-3
Macro graphene:with-quads (vars &body body)
Syntax:
(graphene:with-quads (q1 q2 q3 ... qn) body) => result
Arguments:
q1 ... qn -- newly created graphene:quad-t instances
body -- a body that uses the bindings q1 ... qn
Details:
The graphene:with-quads macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each quadrilateral can be initialized with values using the syntax for the graphene:with-quad macro. See also the graphene:with-quad documentation.
See also:
2025-4-3
Function graphene:quad-alloc ()
Returns:
The newly allocated graphene:quad-t instance.
Details:
Allocates a new graphene:quad-t instance. The contents of the returned instance are undefined.
See also:
2025-4-3
Function graphene:quad-free (q)
Arguments:
q -- a graphene:quad-t instance
Details:
Frees the resources allocated by the graphene:quad-alloc function.
See also:
2025-4-3
Function graphene:quad-init (q p0 p1 p2 p3)
Arguments:
q -- a graphene:quad-t instance
p0 -- a graphene:point-t instance for the first point
p1 -- a graphene:point-t instance for the second point
p2 -- a graphene:point-t instance for the third point
p3 -- a graphene:point-t instance for the fourth point
Returns:
The initialized graphene:quad-t instance.
Details:
Initializes a quadrilateral with the given points.
See also:
2025-4-3
Function graphene:quad-init-from-rect (q r)
Arguments:
q -- a graphene:quad-t instance to initialize
r -- a graphene:rect-t instance
Returns:
The initialized graphene:quad-t instance.
Details:
Initializes a quadrilateral using the four corners of the given rectangle.
See also:
2025-4-3
Function graphene:quad-init-from-points (q values)
Arguments:
q -- a graphene:quad-t instance to initialize
values -- a list of 4 graphene:point-t instances
Returns:
The initialized graphene:quad-t instance.
Details:
Initializes a quadrilateral using a list of points.
See also:
2025-4-3
Function graphene:quad-contains (q p)
Arguments:
q -- a graphene:quad-t instance
p -- a graphene:point-t instance
Returns:
True if the point is inside the graphene:quad-t instance.
Details:
Checks if the given quadrilateral contains the given point.
See also:
2025-4-3
Function graphene:quad-bounds (q result)
Arguments:
q -- a graphene:quad-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the bounding rectangle.
Details:
Computes the bounding rectangle of the quadrilateral.
See also:
2025-4-3
Function graphene:quad-point (q index result)
Arguments:
q -- a graphene:quad-t instance
index -- an integer for the index of the point to retrieve
result -- a graphene:point-t instance
Returns:
The graphene:point-t instance with the given index.
Details:
Retrieves the point of a quadrilateral at the given index.
p0            p1
 + ---------- +
 |            |
 |            |
 |            |
 + ---------- +
p3            p2  
See also:
2025-4-3

Triangle

CStruct graphene:triangle-t
Declaration:
(cffi:defcstruct triangle-t)  
Details:
The graphene:triangle-t structure represents a triangle in 3D space.
2025-4-5
Macro graphene:with-triangle ((var &rest args) &body body)
Syntax:
(graphene:with-triangle (triangle) body) => result
(graphene:with-triangle (triangle p1 p2 p3) body) => result
(graphene:with-triangle (triangle (v1 graphene:vec3-t) v2 v3) body) => result
Arguments:
triangle -- a graphene:triangle-t instance to create and initialize
p1 -- a graphene:point3d-t instance to use for initialization
p2 -- a graphene:point3d-t instance to use for initialization
p3 -- a graphene:point3d-t instance to use for initialization
v1 -- a graphene:vec3-t instance to use for initialization
v2 -- a graphene:vec3-t instance to use for initialization
v3 -- a graphene:vec3-t instance to use for initialization
Details:
The graphene:with-triangle macro allocates a new graphene:triangle-t instance, initializes the triangle with the given values and executes the body that uses the box. After execution of the body the allocated memory for the triangle is released.

When no argument is given the components of the triangle are not definied. The initialization with three points uses the graphene:triangle-init-from-point3d function. If the first value has the graphene:vec3-t type the graphene:triangle-init-from-vec3 is used for initialization with three vectors.
Notes:
The memory is allocated with the graphene:triangle-alloc function and released with the graphene:triangle-free function.
See also:
2025-4-5
Macro graphene:with-triangles (vars &body body)
Syntax:
(graphene:with-triangles (triangle1 ... trianglen) body) => result
Arguments:
triangle1 ... trianglen -- newly created graphene:triangle-t instances
body -- a body that uses the bindings triangle1 ... trianglen
Details:
The graphene:with-triangles macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each point can be initialized with values using the syntax for the graphene:with-triangle macro. See also the graphene:with-triangle documentation.
See also:
2025-4-5
Function graphene:triangle-alloc ()
Returns:
The newly allocated graphene:triangle-t instance.
Details:
Allocates a new graphene:triangle-t instance. The contents of the returned instance are undefined. Use the graphene:triangle-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:triangle-free (triangle)
Arguments:
triangle -- a graphene:triangle-t instance
Details:
Frees the resources allocated by the graphene:triangle-alloc function.
See also:
2025-4-5
Function graphene:triangle-init-from-point3d (triangle a b c)
Arguments:
triangle -- a graphene:triangle-t instance
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
c -- a graphene:point3d-t instance
Returns:
The initialized graphene:triangle-t instance.
Details:
Initializes a triangle using the three given 3D points.
See also:
2025-4-5
Function graphene:triangle-init-from-vec3 (triangle a b c)
Arguments:
triangle -- a graphene:triangle-t instance
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
c -- a graphene:vec3-t instance
Returns:
The initialized graphene:triangle-t instance.
Details:
Initializes a triangle using the three given vectors.
See also:
2025-4-5
Function graphene:triangle-init-from-float (triangle a b c)
Arguments:
triangle -- a graphene:triangle-t instance
a -- a list with 3 numbers coerced to single floats
b -- a list with 3 numbers coerced to single floats
c -- a list with 3 numbers coerced to single floats
Returns:
The initialized graphene:triangle-t instance.
Details:
Initializes a triangle using the three given list of floating point values, each representing the coordinates of a point in 3D space.
See also:
2025-4-5
Function graphene:triangle-points (triangle a b c)
Arguments:
triangle -- a graphene:triangle-t instance
a -- a graphene:point3d-t instance for the first vertex
b -- a graphene:point3d-t instance for the second vertex
c -- a graphene:point3d-t instance for the third vertex
Returns:
The value list of graphene:point3d-t instances with the coordinates of the vertices.
Details:
Retrieves the three vertices of the given triangle and returns their coordinates as graphene:point3d-t instances.
See also:
2025-4-5
Function graphene:triangle-vertices (triangle a b c)
Arguments:
triangle -- a graphene:triangle-t instance
a -- a graphene:vec3-t instance for the first vertex
b -- a graphene:vec3-t instance for the second vertex
c -- a graphene:vec3-t instance for the third vertex
Returns:
The value list of graphene:vec3-t instances with the vertices.
Details:
Retrieves the three vertices of the given triangle.
See also:
2025-4-5
Function graphene:triangle-area (triangle)
Arguments:
triangle -- a graphene:triangle-t instance
Returns:
The single float with the area of the triangle.
Details:
Computes the area of the given triangle.
See also:
2025-4-5
Function graphene:triangle-midpoint (triangle result)
Arguments:
triangle -- a graphene:triangle-t instance
result -- a graphene:point3d-t instance for the coordinates of the midpoint
Returns:
The graphene:point3d-t instance with the coordinates of the midpoint.
Details:
Computes the coordinates of the midpoint of the given triangle. The midpoint is the centroid of the triangle, that is the intersection of its medians.
See also:
2025-4-5
Function graphene:triangle-normal (triangle result)
Arguments:
triangle -- a graphene:triangle-t instance
result -- a graphene:vec3-t instance for the normal vector
Returns:
The graphene:vec3-t instance with the normal vector.
Details:
Computes the normal vector of the given triangle.
See also:
2025-4-5
Function graphene:triangle-plane (triangle result)
Arguments:
triangle -- a graphene:triangle-t instance
result -- a graphene:plane-t instance for the plane
Returns:
The graphene:plane-t instance with the plane.
Details:
Computes the plane based on the vertices of the given triangle.
See also:
2025-4-5
Function graphene:triangle-bounding-box (triangle result)
Arguments:
triangle -- a graphene:triangle-t instance
result -- a graphene:box-t instance for the box
Returns:
The graphene:box-t instance with the box.
Details:
Computes the bounding box of the given triangle.
See also:
2025-4-5
Function graphene:triangle-barycoords (triangle point result)
Arguments:
triangle -- a graphene:triangle-t instance
point -- a graphene:point3d-t instance
result -- a graphene:vec2-t instance for the vector with the barycentric coordinates
Returns:
The graphene:vec2-t instance with the barycentric coordinates, or nil if the result is not valid.
Details:
Computes the barycentric coordinates of the given point. The point must lie on the same plane as the triangle. If the point is not coplanar, the result of this function is undefined.

If we place the origin in the coordinates of the triangle's A point, the barycentric coordinates are u, which is on the AC vector, and v which is on the AB vector.

Figure: Barycentric coordinates

The returned vector contains the following values, in order:
(graphene:vec2-x result) => u
(graphene:vec2-y result) => v  
See also:
2025-4-5
Function graphene:triangle-uv (triangle point a b c result)
Arguments:
triangle -- a graphene:triangle-t instance
point -- a graphene:point3d-t instance
a -- a graphene:vec2-t instance for the UV coordinates of the first point
b -- a graphene:vec2-t instance for the UV coordinates of the second point
c -- a graphene:vec2-t instance for the UV coordinates of the third point
result -- a graphene:vec2-t instance containing the UV coordinates of the given point
Returns:
The graphene:vec2-t instance with the UV coordinates of the given point, of nil if the result is not valid.
Details:
Computes the UV coordinates of the given point. The point must lie on the same plane as the triangle. If the point is not coplanar, the result of this function is undefined. If point is nil, the point will be set to (0, 0, 0).

The UV coordinates will be placed in the result vector:
(graphene:vec2-x result) => u
(graphene:vec2-y result) => v  
See also the graphene:triangle-barycoords function.
See also:
#2025-4-5
Function graphene:triangle-contains-point (triangle point)
Arguments:
triangle -- a graphene:triangle-t instance
point -- a graphene:point3d-t instance
Returns:
True if the point is inside the triangle.
Details:
Checks whether the given triangle contains the point.
See also:
2025-4-5
Function graphene:triangle-equal (a b)
Arguments:
a -- a graphene:triangle-t instance
b -- a graphene:triangle-t instance
Returns:
True if the triangles are equal.
Details:
Checks whether the two given triangles are equal.
See also:
2025-4-5

Box

CStruct graphene:box-t
Declaration:
(cffi:defcstruct box-t)  
Details:
The graphene:box-t structure provides a representation of an axis aligned minimum bounding box using the coordinates of its minimum and maximum vertices.
2025-4-5
Macro graphene:with-box ((var &rest args) &body body)
Syntax:
(graphene:with-box (box) body) => result
(graphene:with-box (box box1) body) => result
(graphene:with-box (box pmin pmax) body) => result
(graphene:with-box (box (vmin graphene:vec3-t) vmax) body) => result
Arguments:
box -- a graphene:box-t instance to create and initialize
box1 -- a graphene:box-t instance to use for initialization
pmin -- a graphene:point3d-t instance to use for initialization
pmax -- a graphene:point3d-t instance to use for initialization
vmin -- a graphene:vec3-t instance to use for initialization
vmax -- a graphene:vec3-t instance to use for initialization
Details:
The graphene:with-box macro allocates a new graphene:box-t instance, initializes the box with the given values and executes the body that uses the box. After execution of the body the allocated memory for the box is released.

When no argument is given the components of the box are initialized to zero. The initialization with two points uses the graphene:box-init function. If the first value has the graphene:vec3-t type the graphene:box-init-from-vec3 function is used for initialization with two vectors. The initialization from another box is done with the graphene:box-init-from-box function.
Notes:
The memory is allocated with the graphene:box-alloc function and released with the graphene:box-free function.
See also:
2025-4-5
Macro graphene:with-boxes (vars &body body)
Syntax:
(graphene:with-boxes (box1 box2 ... boxn) body) => result
Arguments:
box1 ... boxn -- newly created graphene:box-t instances
body -- a body that uses the bindings box1 ... boxn
Details:
The graphene:with-boxes macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each box can be initialized with values using the syntax for the graphene:with-box macro. See also the graphene:with-box documentation.
See also:
2025-4-5
Function graphene:box-alloc ()
Returns:
The newly allocated graphene:box-t instance.
Details:
Allocates a new graphene:box-t instance. The contents of the returned instance are undefined. Use the graphene:box-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:box-free (box)
Arguments:
box -- a graphene:box-t instance
Details:
Frees the resources allocated by the graphene:box-alloc function.
See also:
2025-4-5
Function graphene:box-init (box pmin pmax)
Arguments:
box -- a graphene:box-t instance to initialize
pmin -- a graphene:point3d-t instance for the coordinates of the minimum vertex
pmax -- a graphene:point3d-t instance for the coordinates of the maximum vertex
Returns:
The initialized graphene:box-t instance.
Details:
Initializes the given graphene:box-t instance with two vertices.
See also:
2025-4-5
Function graphene:box-init-from-box (box source)
Arguments:
box -- a graphene:box-t instance to initialize
source -- a graphene:box-t instance
Returns:
The initialized graphene:box-t instance.
Details:
Initializes the given graphene:box-t instance with the vertices of another graphene:box-t instance.
See also:
2025-4-5
Function graphene:box-init-from-vec3 (box vmin vmax)
Arguments:
box -- a graphene:box-t instance to initialize
vmin -- a graphene:vec3-t instance for the coordinates of the minimum vertex
vmax -- a graphene:vec3-t instance for the coordinates of the maximum vertex
Returns:
The initialized graphene:box-t instance.
Details:
Initializes the given graphene:box-t instance with two vertices.
See also:
2025-4-5
Function graphene:box-equal (a b)
Arguments:
a -- a graphene:box-t instance
b -- a graphene:box-t instance
Returns:
True if the boxes are equal, otherwise false
Details:
Checks whether the two given boxes are equal.
See also:
2025-4-5
Function graphene:box-expand (box point result)
Arguments:
box -- a graphene:box-t instance to expand
point -- a graphene:point3d-t instance for the coordinates of the point to include
result -- a graphene:box-t instance for the result
Returns:
The graphene:box-t instance with the result.
Details:
Expands the dimensions of box to include the coordinates at point.
See also:
2025-4-5
Function graphene:box-expand-scalar (box scalar result)
Arguments:
box -- a graphene:box-t instance to expand
scalar -- a number coerced to a single float for the scalar value
result -- a graphene:box-t instance for the result
Returns:
The graphene:box-t instance with the result.
Details:
Expands the dimensions of box by the given scalar value. If the scalar argument is positive, the box will grow. If the scalar argument is negative, the box will shrink.
See also:
2025-4-5
Function graphene:box-expand-vec3 (box vector result)
Arguments:
box -- a graphene:box-t instance to expand
vector -- a graphene:vec3-t instance for the coordinates of the vector to include
result -- a graphene:box-t instance for the result
Returns:
The graphene:box-t instance with the result.
Details:
Expands the dimensions of box to include the coordinates of the given vector.
See also:
2025-4-5
Function graphene:box-min (box pmin)
Arguments:
box -- a graphene:box-t instance
pmin -- a graphene:point3d-t instance for the minimum point
Returns:
The graphene:point3d-t instance with the result.
Details:
Retrieves the coordinates of the minimum point of the given box.
See also:
2025-4-5
Function graphene:box-max (box pmax)
Arguments:
box -- a graphene:box-t instance
pmax -- a graphene:point3d-t instance for the maximum point
Returns:
The graphene:point3d-t instance with the result.
Details:
Retrieves the coordinates of the maximum point of the given box.
See also:
2025-4-5
Function graphene:box-center (box center)
Arguments:
box -- a graphene:box-t instance
center -- a graphene:point3d-t instance for the coordinates of the center
Returns:
The graphene:point3d-t instance with the result.
Details:
Retrieves the coordinates of the center of the box.
See also:
2025-4-5
Function graphene:box-depth (box)
Arguments:
box -- a graphene:box-t instance
Returns:
The single float with the depth of the box.
Details:
Retrieves the size of the box on the Z axis.
See also:
2025-4-5
Function graphene:box-height (box)
Arguments:
box -- a graphene:box-t instance
Returns:
The single float with the height of the box.
Details:
Retrieves the size of the box on the Y axis.
See also:
2025-4-5
Function graphene:box-width (box)
Arguments:
box -- a graphene:box-t instance
Returns:
The single float with the width of the box.
Details:
Retrieves the size of the box on the X axis.
See also:
2025-4-5
Function graphene:box-size (box size)
Arguments:
box -- a graphene:box-t instance
size -- a graphene:vec3-t instance for the size
Returns:
The graphene:vec3-t instance with the size.
Details:
Retrieves the size of the box on all three axes, and stores it into the given size vector.
See also:
2025-4-5
Function graphene:box-bounding-sphere (box sphere)
Arguments:
box -- a graphene:box-t instance
sphere -- a graphene:sphere-t instance for the bounding sphere
Returns:
The graphene:sphere-t instance with the bounding sphere.
Details:
Computes the bounding sphere capable of containing the given box.
See also:
2025-4-5
Function graphene:box-vertices (box vertices)
Arguments:
box -- a graphene:box-t instance
vertices -- a list of eigth graphene:vec3-t instances
Returns:
The list of eight graphene:vec3-t instances with the vertices.
Details:
Computes the vertices of the given box.
Examples:
(graphene:with-vec3s (v0 v1 v2 v3 v4 v5 v6 v7)
  (graphene:with-point3ds ((min 0 0 0) (max 1 1 1))
    (graphene:with-box (box min max)
      (mapcar #'vec3-to-float
              (box-vertices box (list v0 v1 v2 v3 v4 v5 v6 v7))))))
=> ((0.0 0.0 0.0) (0.0 0.0 1.0) (0.0 1.0 0.0) (0.0 1.0 1.0)
    (1.0 0.0 0.0) (1.0 0.0 1.0) (1.0 1.0 0.0) (1.0 1.0 1.0))    
See also:
2025-4-5
Function graphene:box-union (a b result)
Arguments:
a -- a graphene:box-t instance
b -- a graphene:box-t instance
result -- a graphene:box-t instance for the result
Returns:
The graphene:box-t instance with the result.
Details:
Unions the two given boxes.
See also:
2025-4-5
Function graphene:box-intersection (a b result)
Syntax:
(graphene:box-intersection a b result) => result, success
Arguments:
a -- a graphene:box-t instance
b -- a graphene:box-t instance
result -- a graphene:box-t instance for the result
success -- true if the two boxes intersect
Details:
Intersects the two given boxes. If the two boxes do not intersect, result will contain a degenerate box initialized with the graphene:box-empty values.
See also:
2025-4-5
Function graphene:box-contains-box (a b)
Arguments:
a -- a graphene:box-t instance
b -- a graphene:box-t instance
Returns:
True if b is contained in a.
Details:
Checks whether the the box a contains the given box b.
See also:
2025-4-5
Function graphene:box-contains-point (a b)
Arguments:
box -- a graphene:box-t instance
point -- a graphene:point3d-t instance for the coordinates to check
Returns:
True if the point is contained in the box.
Details:
Checks whether the box contains the given point.
See also:
2025-4-5
Function graphene:box-zero ()
Returns:
The graphene:box-t instance.
Details:
Returns a box with both the minimum and maximum vertices set at (0, 0, 0). The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5
Function graphene:box-one ()
Returns:
The graphene:box-t instance.
Details:
Returns a box with both the minimum and maximum vertices set at (1, 1, 1). The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5
Function graphene:box-minus-one ()
Returns:
The graphene:box-t instance.
Details:
Returns a box with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (0, 0, 0). The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5
Function graphene:box-one-minus-one ()
Returns:
The graphene:box-t instance.
Details:
Returns a box the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (1, 1, 1). The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5
Function graphene:box-empty ()
Returns:
The graphene:box-t instance.
Details:
Returns a degenerate box that can only be expanded. The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5
Function graphene:box-infinite ()
Returns:
The graphene:box-t instance.
Details:
Returns a degenerate box that cannot be expanded. The returned box is owned by Graphene and should not be modified or freed.
See also:
2025-4-5

Sphere

CStruct graphene:sphere-t
Declaration:
(cffi:defcstruct sphere-t)  
Details:
The graphene:sphere-t structure provides a representation of a sphere using its center and radius.
2025-4-5
Macro graphene:with-sphere ((var &rest args) &body body)
Syntax:
(graphene:with-sphere (sphere) body) => result
(graphene:with-sphere (sphere sphere1) body) => result
(graphene:with-sphere (sphere center radius) body) => result
Arguments:
sphere -- a graphene:sphere-t instance to create and initialize
sphere1 -- a graphene:sphere-t instance to use for initialization
center -- a graphene:point3d-t instance to use for initialization
radius -- a single float for the radius of the sphere
Details:
The graphene:with-sphere macro allocates a new graphene:sphere-t instance, initializes the sphere with the given values and executes the body that uses the sphere. After execution of the body the allocated memory for the sphere is released.

When no argument is given the components of the sphere are initialized to zero. The initialization from another sphere is done with the graphene:sphere-init-from-sphere function. The initialization with a center and a radius uses the graphene:sphere-init function.
Notes:
The memory is allocated with the graphene:sphere-alloc function and released with the graphene:sphere-free function.
See also:
2025-4-5
Macro graphene:with-spheres (vars &body body)
Syntax:
(graphene:with-spheres (sphere1 sphere2 ... spheren) body) => result
Arguments:
sphere1 ... spheren -- newly created graphene:sphere-t instances
body -- a body that uses the bindings sphere1 ... spheren
Details:
The graphene:with-spheres macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each point can be initialized with values using the syntax for the graphene:with-sphere macro. See also the graphene:with-sphere documentation.
See also:
2025-4-5
Function graphene:sphere-alloc ()
Returns:
The newly allocated graphene:sphere-t instance.
Details:
Allocates a new graphene:sphere-t instance. The contents of the returned instance are undefined. Use the graphene:sphere-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:sphere-free (sphere)
Arguments:
sphere -- a graphene:sphere-t instance
Details:
Frees the resources allocated by the graphene:sphere-alloc function.
See also:
2025-4-5
Function graphene:sphere-init (sphere center radius)
Arguments:
sphere -- a graphene:sphere-t instance to initialize
center -- a graphene:point3d-t instance for the coordinates of the center of the sphere
radius -- a number coerced to a single float for the radius of the sphere
Returns:
The initialized graphene:sphere-t instance.
Details:
Initializes the given graphene:sphere-t instance with the given center and radius.
See also:
2025-4-5
Function graphene:sphere-init-from-points (sphere points center)
Arguments:
sphere -- a graphene:sphere-t instance to initialize
points -- a list of graphene:point3d-t instances
center -- a graphne:point3d-t instance for the center of the sphere, or nil
Returns:
The initialized graphene:sphere-t instance.
Details:
Initializes the given sphere using the given list of 3D coordinates so that the sphere includes them. The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all points.
See also:
2025-4-5
Function graphene:sphere-init-from-vectors (sphere vectors center)
Arguments:
sphere -- a graphene:sphere-t instance to initialize
vectors -- a list of graphene:vec3-t instances
center -- a graphne:point3d-t instance for the center of the sphere, or nil
Returns:
The initialized graphene:sphere-t instance.
Details:
Initializes the given sphere using the given list of 3D coordinates so that the sphere includes them. The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all vectors.
See also:
2025-4-5
Function graphene:sphere-init-from-sphere (sphere source)
Arguments:
sphere -- a graphene:sphere-t instance to initialize
source -- a graphene:sphere-t instance for initialization
Returns:
The initialized graphene:sphere-t instance.
Details:
Initialize a sphere from another sphere.
Notes:
This implementation is added to the Lisp library and not present in the Graphene C library.
See also:
2025-4-5
Function graphene:sphere-center (sphere center)
Arguments:
sphere -- a graphene:sphere-t instance
center -- a graphene:point3d-t instance for the coordinates of the center
Returns:
The graphene:point3d-t instance with the coordinates of the center.
Details:
Retrieves the coordinates of the center of a sphere.
See also:
2025-4-5
Function graphene:sphere-radius (sphere)
Arguments:
sphere -- a graphene:sphere-t instance
Returns:
The single float with the radius.
Details:
Retrieves the radius of a sphere.
See also:
2025-4-5
Function graphene:sphere-bounding-box (sphere box)
Arguments:
sphere -- a graphene:sphere-t instance
box -- a graphene:box-t instance for the bounding box
Returns:
The graphene:box-t instance with the bounding box.
Details:
Computes the bounding box capable of containing the given sphere.
See also:
2025-4-5
Function graphene:sphere-is-empty (sphere)
Arguments:
sphere -- a graphene:sphere-t instance
Returns:
True if the sphere is empty.
Details:
Checks whether the sphere has a zero radius.
See also:
2025-4-5
Function graphene:sphere-distance (sphere point)
Arguments:
sphere -- a graphene:sphere-t instance
point -- a graphene:point3d-t instance
Returns:
The single float with the distance of the point.
Details:
Computes the distance of the given point from the surface of a sphere.
See also:
2025-4-5
Function graphene:sphere-contains-point (sphere point)
Arguments:
sphere -- a graphene:sphere-t instance
point -- a graphene:point3d-t instance
Returns:
True if the sphere contains the point.
Details:
Checks whether the given point is contained in the volume of a sphere.
See also:
2025-4-5
Function graphene:sphere-translate (sphere point result)
Arguments:
sphere -- a graphene:sphere-t instance
point -- a graphene:point3d-t instance for the deltas of the translation
result -- a graphene:sphere-t instance for the translated sphere
Returns:
The graphene:sphere-t instance with the translated sphere.
Details:
Translates the center of the given sphere using the point coordinates as the delta of the translation.
See also:
2025-4-5
Function graphene:sphere-equal (a b)
Arguments:
a -- a graphene:sphere-t instance
b -- a graphene:sphere-t instance
Returns:
True if the spheres are equal.
Details:
Checks whether two spheres are equal.
See also:
2025-4-5

Frustum

CStruct graphene:frustum-t
Declaration:
(cffi:defcstruct frustum-t)  
Details:
The graphene:frustum-t structure represents a volume of space delimited by planes. It is usually employed to represent the field of view of a camera, and can be used to determine whether an object falls within that view, to efficiently remove invisible objects from the render process.

Use the graphene:with-frustum and graphene:with-frustums macros to create and initalize graphene:frustum-t instances.
See also:
2025-4-5
Macro graphene:with-frustum ((var &rest args) &body body)
Syntax:
(graphene:with-frustum (frustum) body) => result
(graphene:with-frustum (frustum frustum1) body) => result
(graphene:with-frustum (frustum (matrix graphene:matrix-t)) body) => result
(graphene:with-frustum (frustum plane0 ... plane5) body) => result
Arguments:
frustum -- a graphene:frustum-t instance to create and initialize
frustum1 -- a graphene:frustum-t instance to use for initialization
matrix -- a graphene:matrix-t instance to use for initialization
plane0 ... plane5 -- six graphene:plane-t instances to use for initialization
Details:
The graphene:with-frustum macro allocates a new graphene:frustum-t instance, initializes the frustum with the given values and executes the body that uses the frustum. After execution of the body the allocated memory for the frustum is released.

When no argument is given the components of the frustum are undefined. The initialization with another frustum uses the graphene:frustum-init-from-frustum function. If the first value has the graphene:matrix-t type the graphene:frustum-init-from-matrix function is used for initialization with the matrix. The initialization from six planes is done with the graphene:frustum-init function.
Notes:
The memory is allocated with the graphene:frustum-alloc function and released with the graphene:frustum-free function.
See also:
2025-4-5
Macro graphene:with-frustums (vars &body body)
Syntax:
(graphene:with-frustums (frustum1 ... frustumn) body) => result
Arguments:
frustum1 ... frustumn -- newly created graphene:frustum-t instances
body -- a body that uses the bindings frustum1 ... frustumn
Details:
The graphene:with-frustums macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each frustum can be initialized with values using the syntax for the graphene:with-frustum macro. See also the graphene:with-frustum documentation.
See also:
2025-4-5
Function graphene:frustum-alloc ()
Returns:
The newly allocated graphene:frustum-t instance.
Details:
Allocates a new graphene:frustum-t instance. The contents of the returned structure are undefined. Use the graphene:frustum-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:frustum-free (frustum)
Arguments:
frustum -- a graphene:frustum-t instance
Details:
Frees the resources allocated by the graphene:frustum-alloc function.
See also:
2025-4-5
Function graphene:frustum-init (frustum p0 p1 p2 p3 p4 p5)
Arguments:
frustum -- a graphene:frustum-t instance to initialize
p0 ... p5 -- six graphene:plane-t instances for the clipping planes
Returns:
The initialized graphene:frustum-t instance.
Details:
Initializes the given graphene:frustum-t instance using the provided clipping planes.
See also:
2025-4-5
Function graphene:frustum-init-from-frustum (frustum source)
Arguments:
frustum -- a graphene:frustum-t instance to initialize
source -- a graphene:frustum-t instance
Returns:
The initialized graphene:frustum-t instance.
Details:
Initializes the given graphene:frustum-t instance using the clipping planes of another graphene:frustum-t instance.
See also:
2025-4-5
Function graphene:frustum-init-from-matrix (frustum matrix)
Arguments:
frustum -- a graphene:frustum-t instance to initialize
matrix -- a graphene:matrix-t instance
Returns:
The initialized graphene:frustum-t instance.
Details:
Initializes the given graphene:frustum-t instance using the given matrix.
See also:
2025-4-5
Function graphene:frustum-planes (frustum planes)
Arguments:
frustum -- a graphene:frustum-t instance
planes -- a list with six graphene:plane-t instances
Returns:
The list of six graphene:plane-t instances.
Details:
Retrieves the planes that define the given graphene:frustum-t instance.
See also:
2025-4-5
Function graphene:frustum-contains-point (frustum point)
Arguments:
frustum -- a graphene:frustum-t instance
point -- a graphene:point3d-t instance
Returns:
True if point is inside frustum.
Details:
Checks whether a point is inside the volume defined by the given frustum.
See also:
2025-4-5
Function graphene:frustum-intersects-sphere (frustum sphere)
Arguments:
frustum -- a graphene:frustum-t instance
sphere -- a graphene:sphere-t instance
Returns:
True if shpere intersects frustum.
Details:
Checks whether the given sphere intersects a plane of the frustum.
See also:
2025-4-5
Function graphene:frustum-intersects-box (frustum box)
Arguments:
frustum -- a graphene:frustum-t instance
box -- a graphene:box-t instance
Returns:
True if box intersects frustum.
Details:
Checks whether the given box intersects a plane of the frustum.
See also:
2025-4-5
Function graphene:frustum-equal (a b)
Arguments:
a -- a graphene:frustum-t instance
b -- a graphene:frustum-t instance
Returns:
True if the given frustums are equal.
Details:
Checks whether the given frustums are equal.
See also:
2025-4-5

Vector

graphene:vec2-t

Constant graphene:+vec2-len+
Initial Value:
2
Details:
Evaluates to the number of components of a graphene:vec2-t structure.
See also:
2025-4-5
CStruct graphene:vec2-t
Declaration:
(cffi:defcstruct vec2-t
  (value :float :count 4)) ; place for 4 single floats  
Details:
The graphene:vec2-t structure is capable of holding a vector with two dimensions x and y. Use the graphene:vec2-x and graphene:vec2-y functions to get the values of the components. There are no functions to set the values directly.
See also:
2025-4-5
Macro graphene:with-vec2 ((var &rest args) &body body)
Syntax:
(graphene:with-vec2 (v) body) => result
(graphene:with-vec2 (v v1) body) => result
(graphene:with-vec2 (v x y) body) => result
Arguments:
v -- a graphene:vec2-t instance to create and initialize
v1 -- a graphene:vec2-t instance to use for initialization
x -- a number coerced to a single float for the x component
y -- a number coerced to a single float for the y component
Details:
The graphene:with-vec2 macro allocates a new graphene:vec2-t instance, initializes the vector with the given values and executes the body that uses the vector. After execution of the body the allocated memory for the vector is released.

When no argument is given the components of the vector are initialized to zero. The initialization from another vector is done with the graphene:vec2-init-from-vec2 function. The initialization with two values x and y uses the graphene:vec2-init function.
Notes:
The memory is allocated with the graphene:vec2-alloc function and released with the graphene:vec2-free function.
See also:
2025-4-5
Macro graphene:with-vec2s (vars &body body)
Syntax:
(graphene:with-vec2s (v1 v2 v3 ... vn) body) => result
Arguments:
v1 ... vn -- newly created graphene:vec2-t instances
body -- a body that uses the bindings v1 ... vn
Details:
The graphene:with-vec2s macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each vector can be initialized with values using the syntax for the graphene:with-vec2 macro. See also the graphene:with-vec2 documentation.
See also:
2025-4-5
Function graphene:vec2-alloc ()
Returns:
The newly allocated graphene:vec2-t instance.
Details:
Allocates a new graphene:vec2-t instance. Use the graphene:vec2-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:vec2-free (v)
Arguments:
v -- a graphene:vec2-t instance
Details:
Frees the resources allocated by v.
See also:
2025-4-5
Function graphene:vec2-init (v x y)
Arguments:
v -- a graphene:vec2-t instance
x -- a number coerced to a single float for the x field of the vector
y -- a number coerced to a single float for the y field of the vector
Returns:
The initialized graphene:vec2-t instance.
Details:
Initializes a graphene:vec2-t instance using the given values. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec2-init-from-vec2 (v source)
Arguments:
v -- a graphene:vec2-t instance
source -- a graphene:vec2-t instance
Returns:
The initialized graphene:vec2-t instance.
Details:
Initializes a graphene:vec2-t instance using another graphene:vec2-t instance. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec2-init-from-float (v arg)
Arguments:
v -- a graphene:vec2-t instance
arg -- a list with two numbers coerced to single floats
Returns:
The initialized graphene:vec2-t instance.
Details:
Initializes v with the contents of the given list.
Notes:
The Lisp implementation does not use the C function, but calls the graphene:vec2-init function to inialize the vector.
(defun vec2-init-from-float (v arg)
  (apply #'graphene:vec2-init v arg))    
See also:
2025-4-5
Function graphene:vec2-to-float (v)
Arguments:
v -- a graphene:vec2-t instance
Returns:
The list with the single floats for the components of v.
Details:
Stores the components of v into a list.
Examples:
(graphene:with-vec2 (v 1/2 3/2) (graphene:vec2-to-float v))
=> (0.5 1.5)    
See also:
2025-4-5
Function graphene:vec2-add (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Adds each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec2-subtract (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Subtracts from each component of the first operand a the corresponding component of the second operand b and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec2-multiply (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Multiplies each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec2-divide (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Divides each component of the first operand a by the corresponding component of the second operand b, and places the results into the vector result.
See also:
2025-4-5
Function graphene:vec2-dot (a b)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
Returns:
The single float with the dot product of the vectors.
Details:
Computes the dot product of the two given vectors.
See also:
2025-4-5
Function graphene:vec2-scale (v factor result)
Arguments:
v -- a graphene:vec2-t instance
factor -- a number coerced to a single float for the scale factor
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result vector.
Details:
Multiplies all components of the given vector with the given scalar factor.
See also:
2025-4-5
Function graphene:vec2-length (v)
Arguments:
v -- a graphene:vec2-t instance
Returns:
The single float with the length of the vector.
Details:
Computes the length of the given vector.
See also:
2025-4-5
Function graphene:vec2-normalize (v result)
Arguments:
v -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the normalized vector.
Details:
Computes the normalized vector for the given vector.
See also:
2025-4-5
Function graphene:vec2-negate (v result)
Arguments:
v -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the negated vector.
Details:
Negates the given vector.
See also:
2025-4-5
Function graphene:vec2-equal (v1 v2)
Arguments:
v1 -- a graphene:vec2-t instance
v2 -- a graphene:vec2-t instance
Returns:
True if the two vectors are equal, and false otherwise
Details:
Checks whether the two given vectors are equal.
See also:
2025-4-5
Function graphene:vec2-near (v1 v2 epsilon)
Arguments:
v1 -- a graphene:vec2-t instance
v2 -- a graphene:vec2-t instance
epsilon -- a number coerced to a single float for the treshold between the two vectors
Returns:
True if the two vectors are near each other, and false otherwise.
Details:
Compares the two given vectors and checks whether their values are within the given epsilon.
See also:
2025-4-5
Function graphene:vec2-min (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Compares the two given vectors and places the minimum values of each component into result.
See also:
2025-4-5
Function graphene:vec2-max (a b result)
Arguments:
a -- a graphene:vec2-t instance
b -- a graphene:vec2-t instance
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the result.
Details:
Compares the two given vectors and places the maximum values of each component into result.
See also:
2025-4-5
Function graphene:vec2-interpolate (v1 v2 factor result)
Arguments:
v1 -- a graphene:vec2-t instance
v2 -- a graphene:vec2-t instance
factor -- a number coerced to a double float for the interpolation factor
result -- a graphene:vec2-t instance for the result
Returns:
The graphene:vec2-t instance with the interpolated vector.
Details:
Linearly interpolates v1 and v2 using the given factor.
See also:
2025-4-5
Function graphene:vec2-x (v)
Arguments:
v -- a graphene:vec2-t instance
Returns:
The single float with the value of the x component.
Details:
Retrieves the x component of the vector.
See also:
2025-4-5
Function graphene:vec2-y (v)
Arguments:
v -- a graphene:vec2-t instance
Returns:
The single float with the value of the y component.
Details:
Retrieves the y component of the vector.
See also:
2025-4-5
Function graphene:vec2-zero ()
Returns:
The graphene:vec2-t instance with (0.0, 0.0) components.
Details:
Retrieves a constant zero vector.
See also:
2025-4-5
Function graphene:vec2-one ()
Returns:
The graphene:vec2-t instance with (1.0, 1.0) components.
Details:
Retrieves a constant one vector.
See also:
2025-4-5
Function graphene:vec2-x-axis ()
Returns:
The graphene:vec2-t instance with the X axis vector.
Details:
Retrieves a constant vector with (1.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec2-y-axis ()
Returns:
The graphene:vec2-t instance with the Y axis vector.
Details:
Retrieves a constant vector with (0.0, 1.0) components.
See also:
2025-4-5

graphene:vec3-t

Constant graphene:+vec3-len+
Initial Value:
3
Details:
Evaluates to the number of components of a graphene:vec3-t structure.
See also:
2025-4-5
CStruct graphene:vec3-t
Declaration:
(cffi:defcstruct vec3-t
  (value :float :count 4)) ; place for 4 single floats  
Details:
The graphene:vec3-t structure is capable of holding a vector with three dimensions x, y, and z. Use the graphene:vec3-x, graphene:vec3-y, and graphene:vec3-z functions to get the values of the components. There are no functions to set the values directly.
See also:
2025-4-5
Macro graphene:with-vec3 ((var &rest args) &body body)
Syntax:
(graphene:with-vec3 (v) body) => result
(graphene:with-vec3 (v v1) body) => result
(graphene:with-vec3 (v x y z) body) => result
Arguments:
v -- a graphene:vec3-t instance to create and initialize
v1 -- a graphene:vec3-t instance to use for initialization
x -- a number coerced to a single float for the x component
y -- a number coerced to a single float for the y component
z -- a number coerced to a single float for the z component
Details:
The graphene:with-vec3 macro allocates a new graphene:vec3-t instance, initializes the vector with the given values and executes the body that uses the vector. After execution of the body the allocated memory for the vector is released.

When no argument is given the components of the vector are initialized to zero. The initialization from another vector is done with the graphene:vec3-init-from-vec3 function. The initialization with three values x, y and z uses the graphene:vec3-init function.
Notes:
The memory is allocated with the graphene:vec3-alloc function and released with the graphene:vec3-free function.
See also:
2025-4-5
Macro graphene:with-vec3s (vars &body body)
Syntax:
(graphene:with-vec3s (v1 v2 v3 ... vn) body) => result
Arguments:
v1 ... vn -- newly created graphene:vec3-t instances
body -- a body that uses the bindings v1 ... vn
Details:
The graphene:with-vec3s macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each vector can be initialized with values using the syntax for the graphene:with-vec3 macro. See also the graphene:with-vec3 documentation.
See also:
2025-4-5
Function graphene:vec3-alloc ()
Returns:
The newly allocated graphene:vec3-t instance.
Details:
Allocates a new graphene:vec3-t instance. Use the graphene:vec3-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:vec3-free (vector)
Arguments:
v -- a graphene:vec3-t instance
Details:
Frees the resources allocated by v.
See also:
2025-4-5
Function graphene:vec3-init (v x y z)
Arguments:
v -- a graphene:vec3-t instance
x -- a number coerced to a single float for the x field of the vector
y -- a number coerced to a single float for the y field of the vector
z -- a number coerced to a single float for the z field of the vector
Returns:
The initialized graphene:vec3-t instance.
Details:
Initializes a graphene:vec3-t instance using the given values. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec3-init-from-vec3 (v source)
Arguments:
v -- a graphene:vec3-t instance
source -- a graphene:vec3-t instance
Returns:
The initialized graphene:vec3-t instance.
Details:
Initializes a graphene:vec3-t instance using another graphene:vec3-t instance. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec3-init-from-float (v arg)
Arguments:
v -- a graphene:vec3-t instance
arg -- a list with three numbers coerced to single floats
Returns:
The initialized graphene:vec3-t instance.
Details:
Initializes v with the contents of the given list.
Notes:
The Lisp implementation does not use the C function, but calls the graphene:vec3-init function to inialize the vector.
(defun vec3-init-from-float (v arg)
  (apply #'vec3-init v arg))    
See also:
2025-4-5
Function graphene:vec3-to-float (v)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The list with the single floats of the components of v.
Details:
Stores the components of v into a list.
See also:
2025-4-5
Function graphene:vec3-add (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Adds each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec3-subtract (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Subtracts from each component of the first operand a the corresponding component of the second operand b and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec3-multiply (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Multiplies each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec3-divide (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Divides each component of the first operand a by the corresponding component of the second operand b, and places the results into the vector result.
See also:
2025-4-5
Function graphene:vec3-cross (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
Returns:
The graphene:vec3-t instance with the result.
Details:
Computes the cross product of the two given vectors.
See also:
2025-4-5
Function graphene:vec3-dot (a b)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
Returns:
The single float with the dot product of the vectors.
Details:
Computes the dot product of the two given vectors.
See also:
2025-4-5
Function graphene:vec3-scale (v factor result)
Arguments:
v -- a graphene:vec3-t instance
factor -- a number coerced to a single float for the scale factor
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result vector.
Details:
Multiplies all components of the given vector with the given scalar factor.
See also:
2025-4-5
Function graphene:vec3-length (v)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The single float with the length of the vector.
Details:
Computes the length of the given vector.
See also:
2025-4-5
Function graphene:vec3-normalize (v result)
Arguments:
v -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the normalized vector.
Details:
Computes the normalized vector for the given vector.
See also:
2025-4-5
Function graphene:vec3-negate (v result)
Arguments:
v -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the negated vector.
Details:
Negates the given vector.
See also:
2025-4-5
Function graphene:vec3-equal (v1 v2)
Arguments:
v1 -- a graphene:vec3-t instance
v2 -- a graphene:vec3-t instance
Returns:
True if the two vectors are equal, and false otherwise
Details:
Checks whether the two given vectors are equal.
See also:
2025-4-5
Function graphene:vec3-near (v1 v2 epsilon)
Arguments:
v1 -- a graphene:vec3-t instance
v2 -- a graphene:vec3-t instance
epsilon -- a number coerced to a single float for the treshold between the two vectors
Returns:
True if the two vectors are near each other, and false otherwise.
Details:
Compares the two given vectors and checks whether their values are within the given epsilon.
See also:
2025-4-5
Function graphene:vec3-min (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Compares the two given vectors and places the minimum values of each component into result.
See also:
2025-4-5
Function graphene:vec3-max (a b result)
Arguments:
a -- a graphene:vec3-t instance
b -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the result.
Details:
Compares the two given vectors and places the maximum values of each component into result.
See also:
2025-4-5
Function graphene:vec3-interpolate (v1 v2 factor result)
Arguments:
v1 -- a graphene:vec3-t instance
v2 -- a graphene:vec3-t instance
factor -- a number coerced to a double float for the interpolation factor
result -- a graphene:vec3-t instance for the result
Returns:
The graphene:vec3-t instance with the interpolated vector.
Details:
Linearly interpolates v1 and v2 using the given factor.
See also:
2025-4-5
Function graphene:vec3-x (v)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The single float with the value of the x component.
Details:
Retrieves the x component of the vector.
See also:
2025-4-5
Function graphene:vec3-y (v)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The single float with the value of the y component.
Details:
Retrieves the y component of the vector.
See also:
2025-4-5
Function graphene:vec3-z (v)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The single float with the value of the z component.
Details:
Retrieves the z component of the vector.
See also:
2025-4-5
Function graphene:vec3-xy (v result)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The graphene:vec2-t instance.
Details:
Returns a graphene:vec2-t instance that contains the first two components of the given vector.
See also:
2025-4-5
Function graphene:vec3-xy0 (v result)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The graphene:vec3-t instance.
Details:
Returns a graphene:vec3-t instance that contains the first two components of the given vector, and the third component set to 0.0.
See also:
2025-4-5
Function graphene:vec3-xyz0 (v result)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The graphene:vec4-t instance.
Details:
Returns a graphene:vec4-t instance that contains the first three components of the given vector, and the fourth component set to 0.0.
See also:
2025-4-5
Function graphene:vec3-xyz1 (v result)
Arguments:
v -- a graphene:vec3-t instance
Returns:
The graphene:vec4-t instance.
Details:
Returns a graphene:vec4-t instance that contains the first three components of the given vector, and the fourth component set to 1.0.
See also:
2025-4-5
Function graphene:vec3-xyzw (v w result)
Arguments:
v -- a graphene:vec3-t instance
w -- a number coerced to a single float for the value of the fourth component
Returns:
The graphene:vec4-t instance.
Details:
Returns a graphene:vec4-t instance that contains the first three components of the given vector, and the fourth component set to w.
See also:
2025-4-5
Function graphene:vec3-zero ()
Returns:
The graphene:vec3-t instance with three components, all sets to 0.0.
Details:
Retrieves a constant zero vector.
See also:
2025-4-5
Function graphene:vec3-one ()
Returns:
The graphene:vec3-t instance with three components, all sets to 1.0.
Details:
Retrieves a constant one vector.
See also:
2025-4-5
Function graphene:vec3-x-axis ()
Returns:
The graphene:vec3-t instance with the X axis vector.
Details:
Retrieves a constant vector with (1.0, 0.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec3-y-axis ()
Returns:
The graphene:vec3-t instance with the Y axis vector.
Details:
Retrieves a constant vector with (0.0, 1.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec3-z-axis ()
Returns:
The graphene:vec3-t instance with the Z axis vector.
Details:
Retrieves a constant vector with (0.0, 0.0, 1.0) components.
See also:
2025-4-5

graphene:vec4-t

Constant graphene:+vec4-len+
Initial Value:
4
Details:
Evaluates to the number of components of a graphene:vec4-t structure.
See also:
2025-4-5
CStruct graphene:vec4-t
Declaration:
(cffi:defcstruct vec4-t
  (value :float :count 4)) ; place for 4 single floats  
Details:
The graphene:vec4-t structure is capable of holding a vector with four dimensions x, y, z and w. Use the graphene:vec4-x, graphene:vec4-y, graphene:vec4-z, and graphene:vec4-w functions to get the values of the components. There are no functions to set the values directly.
See also:
2025-4-5
Macro graphene:with-vec4 ((var &rest args) &body body)
Syntax:
(graphene:with-vec4 (v) body) => result
(graphene:with-vec4 (v v1) body) => result
(graphene:with-vec4 (v v2 w) body) => result
(graphene:with-vec4 (v v3 z w) body) => result
(graphene:with-vec4 (v x y z w) body) => result
Arguments:
v -- a graphene:vec4-t instance to create and initialize
v1 -- a graphene:vec4-t instance to use for initialization
v2 -- a graphene:vec3-t instance to use for initialization
v3 -- a graphene:vec2-t instance to use for initialization
x -- a number coerced to a single float for the x component
y -- a number coerced to a single float for the y component
z -- a number coerced to a single float for the z component
w -- a number coerced to a single float for the w component
Details:
The graphene:with-vec4 macro allocates a new graphene:vec4-t instance, initializes the vector with the given values and executes the body that uses the vector. After execution of the body the allocated memory for the vector is released.

When no argument is given the components of the vector are initialized to zero. The initialization from another vector is done with the graphene:vec4-init-from-vec4 function. The initialization with two values uses the graphene:vec4-init-from-vec3 function and the initialization with three values values uses the graphene:vec4-init-from-vec2 function. At last, the graphene:vec4-init function initializes the vector from four values.
Notes:
The memory is allocated with the graphene:vec4-alloc function and released with the graphene:vec4-free function.
See also:
2025-4-5
Macro graphene:with-vec4s (vars &body body)
Syntax:
(graphene:with-vec4s (v1 v2 v3 ... vn) body) => result
Arguments:
v1 ... vn -- newly created graphene:vec4-t instances
body -- a body that uses the bindings v1 ... vn
Details:
The graphene:with-vec4s macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each vector can be initialized with values using the syntax for the graphene:with-vec4 macro. See also the graphene:with-vec4 documentation.
See also:
2025-4-5
Function graphene:vec4-alloc ()
Returns:
The newly allocated graphene:vec4-t instance.
Details:
Allocates a new graphene:vec4-t instance. Use the graphene:vec4-free function to free the resources allocated by this function.
See also:
2025-4-5
Function graphene:vec4-free (v)
Arguments:
v -- a graphene:vec3-4 instance
Details:
Frees the resources allocated by v.
See also:
2025-4-5
Function graphene:vec4-init (v x y z w)
Arguments:
v -- a graphene:vec4-t instance
x -- a number coerced to a single float for the x field of the vector
y -- a number coerced to a single float for the y field of the vector
z -- a number coerced to a single float for the z field of the vector
w -- a number coerced to a sindle float for the w field of the vector
Returns:
The initialized graphene:vec4-t instance.
Details:
Initializes a graphene:vec4-t instance using the given values. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec4-init-from-vec4 (v source)
Arguments:
v -- a graphene:vec4-t instance
source -- a graphene:vec4-t instance
Returns:
The initialized graphene:vec4-t instance.
Details:
Initializes a graphene:vec4-t instance using another graphene:vec4-t instance. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec4-init-from-vec3 (v src w)
Arguments:
v -- a graphene:vec4-t instance
source -- a graphene:vec4-t instance
w -- a number coerced to a single float for the value of the fourth component of v
Returns:
The initialized graphene:vec4-t instance.
Details:
Initializes a graphene:vec4-t instance using another graphene:vec3-t instance and the value of w. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec4-init-from-vec2 (v src z w)
Arguments:
v -- a graphene:vec4-t instance
source -- a graphene:vec2-t instance
z -- a number coerced to a single float for the value of the third component of v
w -- a number coerced to a single float for the value of the fourth component of v
Returns:
The initialized graphene:vec4-t instance.
Details:
Initializes a graphene:vec4-t instance using another graphene:vec2-t instance and the values of z and w. This function can be called multiple times.
See also:
2025-4-5
Function graphene:vec4-init-from-float (v arg)
Arguments:
v -- a graphene:vec4-t instance
arg -- a list with four numbers coerced to single floats
Returns:
The initialized graphene:vec4-t instance.
Details:
Initializes v with the contents of the given list.
Notes:
The Lisp implementation does not use the C function, but calls the graphene:vec4-init function to inialize the vector.
(defun vec4-init-from-float (v arg)
  (apply #'vec4-init v arg))    
See also:
2025-4-5
Function graphene:vec4-to-float (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The list with the single floats of the components of v.
Details:
Stores the components of v into a list.
See also:
2025-4-5
Function graphene:vec4-add (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Adds each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec4-subtract (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Subtracts from each component of the first operand a the corresponding component of the second operand b and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec4-multiply (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Multiplies each component of the two passed vectors and places each result into the components of result.
See also:
2025-4-5
Function graphene:vec4-divide (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Divides each component of the first operand a by the corresponding component of the second operand b, and places the results into the vector result.
See also:
2025-4-5
Function graphene:vec4-dot (a b)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
Returns:
The single float with the dot product of the vectors.
Details:
Computes the dot product of the two given vectors.
See also:
2025-4-5
Function graphene:vec4-scale (v factor result)
Arguments:
v -- a graphene:vec4-t instance
factor -- a number coerced to a single float for the scale factor
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result vector.
Details:
Multiplies all components of the given vector with the given scalar factor.
See also:
2025-4-5
Function graphene:vec4-length (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The single float with the length of the vector.
Details:
Computes the length of the given vector.
See also:
2025-4-5
Function graphene:vec4-normalize (v result)
Arguments:
v -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the normalized vector.
Details:
Computes the normalized vector for the given vector.
See also:
2025-4-5
Function graphene:vec4-negate (v result)
Arguments:
v -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the negated vector.
Details:
Negates the given vector.
See also:
2025-4-5
Function graphene:vec4-equal (v1 v2)
Arguments:
v1 -- a graphene:vec4-t instance
v2 -- a graphene:vec4-t instance
Returns:
True if the two vectors are equal, and false otherwise
Details:
Checks whether the two given vectors are equal.
See also:
2025-4-5
Function graphene:vec4-near (v1 v2 epsilon)
Arguments:
v1 -- a graphene:vec4-t instance
v2 -- a graphene:vec4-t instance
epsilon -- a number coerced to a single float for the treshold between the two vectors
Returns:
True if the two vectors are near each other, and false otherwise.
Details:
Compares the two given vectors and checks whether their values are within the given epsilon.
See also:
2025-4-5
Function graphene:vec4-min (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Compares the two given vectors and places the minimum values of each component into result.
See also:
2025-4-5
Function graphene:vec4-max (a b result)
Arguments:
a -- a graphene:vec4-t instance
b -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the result.
Details:
Compares the two given vectors and places the maximum values of each component into result.
See also:
2025-4-5
Function graphene:vec4-interpolate (v1 v2 factor result)
Arguments:
v1 -- a graphene:vec4-t instance
v2 -- a graphene:vec4-t instance
factor -- a number coerced to a double float for the interpolation factor
result -- a graphene:vec4-t instance for the result
Returns:
The graphene:vec4-t instance with the interpolated vector.
Details:
Linearly interpolates v1 and v2 using the given factor.
See also:
2025-4-5
Function graphene:vec4-x (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The single float with the value of the x component.
Details:
Retrieves the x component of the vector.
See also:
2025-4-5
Function graphene:vec4-y (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The single float with the value of the y component.
Details:
Retrieves the y component of the vector.
See also:
2025-4-5
Function graphene:vec4-z (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The single float with the value of the z component.
Details:
Retrieves the z component of the vector.
See also:
2025-4-5
Function graphene:vec4-w (v)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The single float with the value of the fourth component.
Details:
Retrieves the fourth component of the vector.
See also:
2025-4-5
Function graphene:vec4-xy (v result)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The graphene:vec2-t instance.
Details:
Returns a graphene:vec2-t instance that contains the first two components of the given vector.
See also:
2025-4-5
Function graphene:vec4-xyz (v result)
Arguments:
v -- a graphene:vec4-t instance
Returns:
The graphene:vec3-t instance.
Details:
Returns a graphene:vec3-t instance that contains the first three components of the given vector.
See also:
2025-4-5
Function graphene:vec4-zero ()
Returns:
The graphene:vec4-t instance with three components, all sets to 0.0.
Details:
Retrieves a constant zero vector.
See also:
2025-4-5
Function graphene:vec4-one ()
Returns:
The graphene:vec4-t instance with three components, all sets to 1.0.
Details:
Retrieves a constant one vector.
See also:
2025-4-5
Function graphene:vec4-x-axis ()
Returns:
The graphene:vec4-t instance with the X axis vector.
Details:
Retrieves a constant vector with (1.0, 0.0, 0.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec4-y-axis ()
Returns:
The graphene:vec4-t instance with the Y axis vector.
Details:
Retrieves a constant vector with (0.0, 1.0, 0.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec4-z-axis ()
Returns:
The graphene:vec4-t instance with the Z axis vector.
Details:
Retrieves a constant vector with (0.0, 0.0, 1.0, 0.0) components.
See also:
2025-4-5
Function graphene:vec4-w-axis ()
Returns:
The graphene:vec4-t instance with the w axis vector.
Details:
Retrieves a constant vector with (0.0, 0.0, 0.0, 1.0) components.
See also:
2025-4-5

Matrix

CStruct graphene:matrix-t
Declaration:
(cffi:defcstruct matrix-t)  
Details:
The graphene:matrix-t structure is a type that provides a 4x4 square matrix, useful for representing 3D transformations. The matrix is treated as row-major, that is, it has four vectors x, y, z, and w representing rows, and elements of each vector are a column:
⎡ m.x ⎤      ⎛ x.x  x.y  x.z  x.w ⎞
⎜ m.y ⎟  =>  ⎜ y.x  y.y  y.z  y.w ⎟
⎜ m.z ⎟      ⎜ z.x  z.y  z.z  z.w ⎟
⎣ m.w ⎦      ⎝ w.x  w.y  w.z  w.w ⎠  
It is possible to easily convert a graphene:matrix-t instance to and from an array of floating point values that can be used with other libraries.

The contents of a graphene:matrix-t instance are private, and direct access is not possible. You can modify and read the contents of a graphene:matrix-t instance only through the provided API.

Conventions
Graphene uses left-multiplication for all its operations on vectors and matrices. In other words, given a matrix A and a vector b, the result of a multiplication is going to be:
res = b × A  
Multiplying two matrices, on the other hand, will use right-multiplication. Given two matrices A and B, the result of the multiplication is going to be
res = A × B  
as the implementation will multiply each row vector of matrix A with the matrix B to obtain the new row vectors of the result matrix:
res = ⎡ A.x × B ⎤
      ⎜ A.y × B ⎟
      ⎜ A.z × B ⎟
      ⎣ A.w × B ⎦  
2025-4-6
Macro graphene:with-matrix ((var &rest args) &body body)
Syntax:
(graphene:with-matrix (m) body) => result
(graphene:with-matrix (m m1) body) => result
(graphene:with-matrix (m (p graphene:point3d-t)) body) => result
(graphene:with-matrix (m angle (axis graphene:vec3-t)) body) => result
(graphene:with-matrix (m xskew yskew) body) => result
(graphene:with-matrix (m x y z) body) => result
(graphene:with-matrix (m (eye graphene:vec3-t) center up) body) => result
(graphene:with-matrix (m fovy aspect znear zfar) body) => result
(graphene:with-matrix (m (v0 graphene:vec4-t) v1 v2 v3) body) => result
(graphene:with-matrix (m left right top bottom znear zfar) body) => result
(graphene:with-matrix (m (xx :double) yx xy yy x0 y0) body) => result
(graphene:with-matrix (m &rest args) body) => result
Arguments:
m -- a graphene:matrix-t instance to create and initialize
m1 -- a graphene:matrix-t instance to use for initialization
p -- a graphene:point3d-t instance
axis, eye, center, up -- a graphene:vec3-t instance
v0,v1,v2,v3 -- a graphene:vec4-t instance
xx, yx, xy, yy, x0, y0 -- a double float
other values -- a single float
Details:
The graphene:with-matrix macro allocates a new graphene:matrix-t instance, initializes the matrix with the given values and executes the body that uses the matrix. After execution of the body the allocated memory for the matrix is released.

The macro uses the following function for intialization of the matrix:
Notes:
The memory is allocated with the graphene:matrix-alloc function and released with the graphene:matrix-free function.
See also:
2025-4-6
Macro graphene:with-matrices (vars &body body)
Syntax:
(graphene:with-matrices (matrix1 ... matrixn) body) => result
Arguments:
matrix1 ... matrixn -- newly created graphene:matrix-t instances
body -- a body that uses the bindings matrix1 ... matrixn
Details:
The graphene:with-matrices macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each matrix can be initialized with values using the syntax for the graphene:with-matrix macro. See also the graphene:with-matrix documentation.
See also:
2025-4-6
Function graphene:matrix-alloc ()
Returns:
The newly allocated graphene:matrix-t instance.
Details:
Allocates a new graphene:matrix-t instance. The contents of the returned structure are undefined.
See also:
2025-4-6
Function graphene:matrix-free (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Details:
Frees the resources allocated by the graphene:matrix-alloc function.
See also:
2025-4-6
Function graphene:matrix-init-identity (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with the identity matrix.
See also:
2025-4-6
Function graphene:matrix-init-from-float (matrix &rest args)
Arguments:
matrix -- a graphene:matrix-t instance
values -- 16 numbers coerced to single floats
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with the given numbers.
See also:
2025-4-6
Function graphene:matrix-init-from-vec4 (m v0 v1 v2 v3)
Arguments:
m -- a graphene:matrix-t instance
v0 -- a graphene:vec4-t instance for a row vector
v1 -- a graphene:vec4-t instance for a row vector
v2 -- a graphene:vec4-t instance for a row vector
v3 -- a graphene:vec4-t instance for a row vector
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with the given four row vectors.
See also:
2025-4-6
Function graphene:matrix-init-from-matrix (matrix source)
Arguments:
matrix -- a graphene:matrix-t instance
source -- a graphene:matrix-t instance
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix using the values of the given matrix.
See also:
2025-4-6
Function graphene:matrix-init-from-2d (matrix xx yx xy yy x0 y0)
Arguments:
matrix -- a graphene:matrix-t instance
xx -- a number for the xx member
yx -- a number for the yx member
xy -- a number for the xy member
yy -- a number for the yy member
x0 -- a number for the x0 member
y0 -- a number for the y0 member
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix from the values of an affine transformation matrix. The arguments map to the following matrix layout:
⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠  
This function can be used to convert between an affine matrix type from other libraries and a graphene:matrix-t instance.
Notes:
All numbers are coerced to double floats before being passed to the foreign C function.
See also:
2025-4-6
Function graphene:matrix-init-perspective (matrix fovy aspect znear zfar)
Arguments:
matrix -- a graphene:matrix-t instance
fovy -- a number for the field of view angle, in degrees
aspect -- a number for the aspect value
znear -- a number for the near z plane
zfar -- a number for the far z plane
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with a perspective projection.
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
2025-4-6
Function graphene:matrix-init-ortho (matrix left right top bottom znear zfar)
Arguments:
matrix -- a graphene:matrix-t instance
left -- a number for the left edge of the clipping plane
right -- a number for the right edge of the clipping plane
top -- a number for the top edge of the clipping plane
bottom -- a number for the bottom edge of the clipping plane
znear -- a number for the distance of the near clipping plane
zfar -- a number for the distance of the far clipping plane
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with an orthographic projection.
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-init-look-at (matrix eye center up)
Arguments:
matrix -- a graphene:matrix-t instance
eye -- a graphene:vec3-t instance for the vector describing the position to look from
center -- a graphene:vec3-t instance for the vector describing the position at
up -- a graphene:vec3-t instance for the vector describing the world's upward direction, usually, this is the Y axis vector returned from the graphene:vec3-y-axis function
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix so that it positions the "camera" at the given eye coordinates towards an object at the center coordinates. The top of the camera is aligned to the direction of the up vector.

Before the transform, the camera is assumed to be placed at the origin, looking towards the negative Z axis, with the top side of the camera facing in the direction of the Y axis and the right side in the direction of the X axis.

In theory, one could use matrix to transform a model of such a camera into world-space. However, it is more common to use the inverse of matrix to transform another object from world coordinates to the view coordinates of the camera. Typically you would then apply the camera projection transform to get from view to screen coordinates.
See also:
#2025-4-6
Function graphene:matrix-init-frustum (matrix left right bottom top znear zfar)
Arguments:
matrix -- a graphene:matrix-t instance
left -- a number for the left edge of the clipping plane
right -- a number for the right edge of the clipping plane
top -- a number for the top edge of the clipping plane
bottom -- a number for the bottom edge of the clipping plane
znear -- a number for the distance of the near clipping plane
zfar -- a number for the distance of the far clipping plane
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix compatible with a frustum. The matrix is initialized with the following components:
⎛ 2*n/(r-l)     0              0              0 ⎞
⎜ 0             2*n/(t-b)      0              0 ⎟
⎜ (r+l)/(r-l)   (t+b)/(t-b)   -(f+n)/(f-n)   -1 ⎟
⎝ 0             0             -2*f*n/(f-n)    0 ⎠

l = left, r = right, b = bottom, t = top, n = znear, f = zfar
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
2025-4-6
Function graphene:matrix-init-scale (matrix x y z)
Arguments:
matrix -- a graphene:matrix-t instance
x -- a number for the scale factor on the X axis
y -- a number for the scale factor on the Y axis
z -- a number for the scale factor on the Z axis
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with the given scaling factors.
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-init-translate (matrix point)
Arguments:
matrix -- a graphene:matrix-t instance
point -- a graphene:point3d-t instance for the translation coordinates
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with a translation to given coordinates.
See also:
#2025-4-6
Function graphene:matrix-init-rotate (matrix angle axis)
Arguments:
matrix -- a graphene:matrix-t instance
angle -- a number for the rotation angle, in degrees
axis -- a graphene:vec3-t instance for the axis vector
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix to represent a rotation of angle degrees on the axis represented by the axis vector.
Notes:
The angle argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-init-skew (matrix xskew yskew)
Arguments:
matrix -- a graphene:matrix-t instance
xskew -- a number for the skew factor, in radians, on the X axis
yskew -- a number for the skew factor, in radians, on the Y axis
Returns:
The initialized graphene:matrix-t instance.
Details:
Initializes the matrix with a skew transformation with the given factors.
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-is-identity (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
True if matrix is the identity matrix.
Details:
Checks whether the given matrix is the identity matrix.
See also:
2025-4-6
Function graphene:matrix-is-2d (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
True if matrix is compatible with an affine transformation matrix.
Details:
Checks whether the given matrix is compatible with an a 2D affine transformation matrix.
See also:
2025-4-6
Function graphene:matrix-is-backface-visible (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
True if the back face of matrix is visible.
Details:
Checks whether the matrix has a visible back face.
See also:
2025-4-6
Function graphene:matrix-is-singular (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
True if matrix is singular.
Details:
Checks whether the matrix is singular.
See also:
2025-4-6
Function graphene:matrix-to-float (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The list with the single floats.
Details:
Converts the matrix to a list of floating point values.
See also:
2025-4-6
Function graphene:matrix-to-2d (matrix)
Syntax:
(graphene:matrix-to-2d matrix) => (list xx yx xy yy x0 y0)
Arguments:
matrix -- a graphene:matrix-t instance
xx -- a double float for the xx member
yx -- a double float for the yx member
xy -- a double float for the xy member
yy -- a double float for the yy member
x0 -- a double float for the x0 member
y0 -- a double float for the y0 member
Returns:
The list with the single floats, or nil if matrix is not compatible with an affine transformation matrix.
Details:
Converts the matrix to an affine transformation matrix, if the given matrix is compatible. The returned values have the following layout:
⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠  
This function can be used to convert between a graphene:matrix-t instance and an affine matrix type from other libraries.
See also:
2025-4-6
Function graphene:matrix-row (matrix index result)
Arguments:
matrix -- a graphene:matrix-t instance
index -- an unsigned integer for the index of the row vector
result -- a graphene:vec4-t instance
Returns:
The graphene:vec4-t instance with the row vector.
Details:
Retrieves the given row vector at index inside the matrix.
See also:
2025-4-6
Function graphene:matrix-value (matrix row col)
Arguments:
matrix -- a graphene:matrix-t instance
row -- an unsigned integer for the row index
col -- an unsigned integer for the column index
Returns:
The single float at the given indices.
Details:
Retrieves the value at the given row and col index.
See also:
2025-4-6
Function graphene:matrix-multiply (a b result)
Arguments:
a -- a graphene:matrix-t instance
b -- a graphene:matrix-t instance
result -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance with the matrix result.
Details:
Multiplies two matrices. Matrix multiplication is not commutative in general. The order of the factors matters. The product of this multiplication is (a × b ).
See also:
#2025-4-6
Function graphene:matrix-determinant (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the value of the determinat.
Details:
Computes the determinant of the given matrix.
See also:
#2025-4-6
Function graphene:matrix-transform-vec4 (matrix vector result)
Arguments:
matrix -- a graphene:matrix-t instance
vector -- a graphene:vec4-t instance
result -- a graphene:vec4-t instance
Returns:
The graphene:vec4-t instance with the result.
Details:
Transforms the given vector using the given matrix.
See also:
#2025-4-6
Function graphene:matrix-transform-vec3 (matrix vector result)
Arguments:
matrix -- a graphene:matrix-t instance
vector -- a graphene:vec3-t instance
result -- a graphene:vec3-t instance
Returns:
The graphene:vec3-t instance with the result.
Details:
Transforms the given vector using the given matrix. This function will multiply the x, y, and z row vectors of matrix with the corresponding components of vector. The w row vector will be ignored.
See also:
#2025-4-6
Function graphene:matrix-transform-point (matrix point result)
Arguments:
matrix -- a graphene:matrix-t instance
point -- a graphene:point-t instance
result -- a graphene:point-t instance
Returns:
The graphene:point-t instance with the result.
Details:
Transforms the given point using the given matrix. Unlike the graphene:matrix-transform-vec3 function, this function will take into account the fourth row vector of the matrix when computing the dot product of each row vector of the matrix.
See also:
#2025-4-6
Function graphene:matrix-transform-point3d (matrix point result)
Arguments:
matrix -- a graphene:matrix-t instance
point -- a graphene:point3d-t instance
result -- a graphene:point3d-t instance
Returns:
The graphene:point3d-t instance with the result.
Details:
Transforms the given point using the given matrix. Unlike the graphene:matrix-transform-vec3 function, this function will take into account the fourth row vector of the matrix when computing the dot product of each row vector of the matrix.
See also:
#2025-4-6
Function graphene:matrix-transform-rect (matrix rect result)
Arguments:
matrix -- a graphene:matrix-t instance
rect -- a graphene:rect-t instance
result -- a graphene:quad-t instance
Returns:
The graphene:quad-t instance with the result.
Details:
Transforms each corner of the rectangle using the given matrix. The result is a coplanar quadrilateral. See also the graphene:matrix-transform-point function.
See also:
#2025-4-6
Function graphene:matrix-transform-bounds (matrix rect result)
Arguments:
matrix -- a graphene:matrix-t instance
rect -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the bounds of the transformed rectangle.
Details:
Transforms each corner of the rectangle using the given matrix. The result is the axis aligned bounding rectangle containing the coplanar quadrilateral. See also the graphene:matrix-transform-point function.
See also:
#2025-4-6
Function graphene:matrix-transform-box (matrix box result)
Arguments:
matrix -- a graphene:matrix-t instance
box -- a graphene:box-t instance
result -- a graphene:box-t instance
Returns:
The graphene:box-t instance with the bounds the transformed box.
Details:
Transforms the vertices of the box using the given matrix. The result is the axis aligned bounding box containing the transformed vertices.
See also:
#2025-4-6
Function graphene:matrix-transform-sphere (matrix sphere result)
Arguments:
matrix -- a graphene:matrix-t instance
sphere -- a graphene:sphere-t instance
result -- a graphene:sphere-t instance
Returns:
The graphene:sphere-t instance with the bounds of the transformed sphere.
Details:
Transforms the sphere using the given matrix. The result is the bounding sphere containing the transformed sphere.
See also:
#2025-4-6
Function graphene:matrix-transform-ray (matrix ray result)
Arguments:
matrix -- a graphene:matrix-t instance
ray -- a graphene:ray-t instance
result -- a graphene:ray-t instance
Returns:
The graphene:ray-t instance with the transformed ray.
Details:
Transforms the ray using the given matrix.
See also:
#2025-4-6
Function graphene:matrix-project-point (matrix point result)
Arguments:
matrix -- a graphene:matrix-t instance
point -- a graphene:point-t instance
result -- a graphene:point-t instance
Returns:
The graphene:point-t instance with the projected point.
Details:
Projects the point using the given matrix.
See also:
#2025-4-6
Function graphene:matrix-project-rect-bounds (matrix rect result)
Arguments:
matrix -- a graphene:matrix-t instance
rect -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the projected rectangle.
Details:
Projects the rectangle using the given matrix. The resulting rectangle is the axis aligned bounding rectangle capable of fully containing the projected rectangle.
See also:
#2025-4-6
Function graphene:matrix-project-rect (matrix rect result)
Arguments:
matrix -- a graphene:matrix-t instance
rect -- a graphene:rect-t instance
result -- a graphene:quad-t instance
Returns:
The graphene:quad-t instance with the projected rectangle.
Details:
Projects all corners of the rectangle using the given matrix. See also the graphene:matrix-project-point function.
See also:
#2025-4-6
Function graphene:matrix-untransform-point (matrix point bounds result)
Arguments:
matrix -- a graphene:matrix-t instance
point -- a graphene:point-t instance
bounds -- a graphene:rect-t instance
result -- a graphene:point-t instance
Returns:
The graphene:point-t instance with the untransformed point, if sucessfully, otherwise nil.
Details:
Undoes the transformation of the point using the given matrix, within the given axis aligned rectangular bounds.
See also:
#2025-4-6
Function graphene:matrix-untransform-bounds (matrix rect bounds result)
Arguments:
matrix -- a graphene:matrix-t instance
rect -- a graphene:rect-t instance
bounds -- a graphene:rect-t instance
result -- a graphene:rect-t instance
Returns:
The graphene:rect-t instance with the untransformed rectangle.
Details:
Undoes the transformation on the corners of the rectangle using the given matrix, within the given axis aligned rectangular bounds.
See also:
#2025-4-6
Function graphene:matrix-unproject-point3d (projection modelview point result)
Arguments:
projection -- a graphene:matrix-t instance
modelview -- a graphene:matrix-t instance
point -- a graphene:point3d-t instance
result -- a graphene:point3d-t instance
Returns:
The graphene:point3d-t instance with the unprojected point.
Details:
Unprojects the given point using the projection matrix and a modelview matrix.
See also:
#2025-4-6
Function graphene:matrix-translate (matrix pos)
Arguments:
matrix -- a graphene:matrix-t instance
pos -- a graphene:point3d-t instance
Returns:
The graphene:matrix instance with the result.
Details:
Adds a translation transformation to the matrix using the coordinates of the given point. This is the equivalent of calling the graphene:matrix-init-translate function and then multiplying the matrix with the translation matrix. graphene:matrix-init-translate
See also:
#2025-4-6
Function graphene:matrix-rotate (matrix angle axis)
Arguments:
matrix -- a graphene:matrix-t instance
angle -- a number for the rotation angle, in degrees
axis -- a graphene:vec3-t instance with rotation axis
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a rotation transformation to the matrix, using the given angle and axis vector. This is the equivalent of calling the graphene:matrix-init-rotate function and then multiplying the matrix with the rotation matrix.
Notes:
The angle argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-rotate-x (matrix angle)
Arguments:
matrix -- a graphene:matrix-t instance
angle -- a number for the rotation angle, in degrees
Returns:
The graphene:matrix instance with the result.
Details:
Adds a rotation transformation around the X axis to the matrix, using the given angle. See also the graphene:matrix-rotate function.
Notes:
The angle argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-rotate-y (matrix angle)
Arguments:
matrix -- a graphene:matrix-t instance
angle -- a number for the rotation angle, in degrees
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a rotation transformation around the Y axis to the matrix, using the given angle. See also the graphene:matrix-rotate function.
Notes:
The angle argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-rotate-z (matrix angle)
Arguments:
matrix -- a graphene:matrix-t instance
angle -- a number for the rotation angle, in degrees
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a rotation transformation around the Z axis to the matrix, using the given angle. See also the graphene:matrix-rotate function.
Notes:
The angle argument is coerced to single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-rotate-quaternion (matrix quaternion)
Arguments:
matrix -- a graphene:matrix-t instance
quaternion -- a graphene:quaternion-t instance
Details:
Adds a rotation transformation to the matrix, using the given quaternion. This is the equivalent of calling the graphene:quaternion-to-matrix function and then multiplying the matrix with the rotation matrix.
See also:
#2025-4-6
Function graphene:matrix-rotate-euler (matrix euler)
Arguments:
matrix -- a graphene:matrix-t instance
euler -- a graphene:euler-t instance
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a rotation transformation to the matrix, using the given euler angles.
See also:
#2025-4-6
Function graphene:matrix-scale (matrix xfactor yfactor zfactor)
Arguments:
matrix -- a graphene:matrix-t instance
xfactor -- a number for the scaling factor on the X axis
yfactor -- a number for the scaling factor on the Y axis
zfactor -- a number for the scaling factor on the Z axis
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a scaling transformation to the matrix, using the three given factors. This is the equivalent of calling the graphene:matrix-init-scale function and then multiplying the matrix with the scale matrix.
Notes:
All numbers are coerced to single floats before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-skew-xy (matrix factor)
Arguments:
matrix -- a graphene:matrix-t instance
factor -- a number for the skew factor
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a skew of factor on the X and Y axis to the given matrix.
Notes:
The factor argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-skew-xz (matrix factor)
Arguments:
matrix -- a graphene:matrix-t instance
factor -- a number for the skew factor
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a skew of factor on the X and Z axis to the given matrix.
Notes:
The factor argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-skew-yz (matrix factor)
Arguments:
matrix -- a graphene:matrix-t instance
factor -- a number for the skew factor
Returns:
The graphene:matrix-t instance with the result.
Details:
Adds a skew of factor on the Y and Z axis to the given matrix.
Notes:
The factor argument is coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-transpose (matrix result)
Arguments:
matrix -- a graphene:matrix-t instance
result -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance with the transposed matrix.
Details:
Transposes the given matrix.
See also:
#2025-4-6
Function graphene:matrix-inverse (matrix result)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance with the inversed matrix, nil if the matrix is not invertible.
Details:
Inverts the given matrix.
See also:
#2025-4-6
Function graphene:matrix-perspective (matrix depth result)
Arguments:
matrix -- a graphene:matrix-t instance
depth -- a number for the depth of the perspective
Returns:
The graphene:matrix-t instance with the perpective matrix.
Details:
Applies a perspective of depth to the matrix.
Notes:
The depth argument ist coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-normalize (matrix result)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance with the normalized matrix.
Details:
Normalizes the given matrix.
See also:
#2025-4-6
Function graphene:matrix-x-translation (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the translation component.
Details:
Retrieves the translation component on the X axis from the given matrix.
See also:
#2025-4-6
Function graphene:matrix-y-translation (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the translation component.
Details:
Retrieves the translation component on the Y axis from the given matrix.
See also:
#2025-4-6
Function graphene:matrix-z-translation (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the translation component.
Details:
Retrieves the translation component on the Z axis from the given matrix.
See also:
#2025-4-6
Function graphene:matrix-x-scale (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the scaling factor.
Details:
Retrieves the scaling factor on the X axis in the given matrix.
See also:
#2025-4-6
Function graphene:matrix-y-scale (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the scaling factor.
Details:
Retrieves the scaling factor on the Y axis in the given matrix.
See also:
#2025-4-6
Function graphene:matrix-z-scale (matrix)
Arguments:
matrix -- a graphene:matrix-t instance
Returns:
The single float with the scaling factor.
Details:
Retrieves the scaling factor on the Z axis in the given matrix.
See also:
#2025-4-6
Function graphene:matrix-decompose (matrix translate scale rotate shear perspective)
Arguments:
matrix -- a graphene:matrix-t instance
translate -- a graphene:vec3-t instance
scale -- a graphene:vec3-t instance
rotate -- a graphene:quaternion-t instance
shear -- a graphene:vec3-t instance
perspective -- a graphene:vec4-t instance
Returns:
True if the matrix could be composed.
Details:
Decomposes a transformation matrix into its component transformations.

The algorithm for decomposing a matrix is taken from the CSS3 Transforms specification. Specifically, the decomposition code is based on the equivalent code published in "Graphics Gems II", edited by Jim Arvo, and available online.
See also:
#2025-4-6
Function graphene:matrix-interpolate (a b factor result)
Arguments:
a -- a graphene:matrix-t instance
b -- a graphene:vec3-t instance
factor -- a number for the linear interpolation factor
result -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance with the interpolated matrix.
Details:
Linearly interpolates the two given matrices by interpolating the decomposed transformations separately. If either matrix cannot be reduced to their transformations then the interpolation cannot be performed, and this function will return an identity matrix.
Notes:
The factor argument ist coerced to a double float before being passed to the foreign C function.
See also:
#2025-4-6
Function graphene:matrix-equal (a b)
Arguments:
a -- a graphene:matrix-t instance
b -- a graphene:vec3-t instance
Returns:
True if the two matrices are equal, false otherwise.
Details:
Checks whether the two given matrices are equal.
See also:
#2025-4-6
Function graphene:matrix-equal-fast (a b)
Arguments:
a -- a graphene:matrix-t instance
b -- a graphene:vec3-t instance
Returns:
True if the two matrices are equal, false otherwise.
Details:
Checks whether the two given matrices are byte-by-byte equal.

While this function is faster than the graphene:matrix-equal function, it can also return false negatives, so it should be used in conjuction with either the graphene:matrix-equal or graphene:matrix-near function. For instance:
if (graphene_matrix_equal_fast (a, b))
  {
    // matrices are definitely the same
  }
else
  {
    if (graphene_matrix_equal (a, b))
      // matrices contain the same values within an epsilon of FLT_EPSILON
    else if (graphene_matrix_near (a, b, 0.0001))
      // matrices contain the same values within an epsilon of 0.0001
    else
      // matrices are not equal
  }  
See also:
#2025-4-6
Function graphene:matrix-near (a b epsilon)
Arguments:
a -- a graphene:matrix-t instance
b -- a graphene:matrix-t instance
epsilon -- a single float for the threshold between the two matrices
Returns:
True if the two matrices are near each other, false otherwise.
Details:
Compares the two given matrices and checks whether their values are within the given epsilon of each other.
Notes:
The epsilon argument ist coerced to a single float before being passed to the foreign C function.
See also:
#2025-4-6

Euler

CEnum graphene:euler-order-t
Declaration:
(cffi:defcenum euler-order-t
  :default
  ;; Deprecated since Graphene 1.10
  :XYZ  :YZX  :ZXY  :XZY  :YXZ  :ZYX
  ;; Static rotations
  :SXYZ :SXYX :SXZY :SXZX
  :SYZX :SYZY :SYXZ :SYXY
  :SZXY :SZXZ :SZYX :SZYZ
  ;; Relative rotations
  :RZYX :RXYX :RYZX :RXZX
  :RXZY :RYZY :RZXY :RYXY
  :RYXZ :RZXZ :RXYZ :RZYZ)  
Values:
:default
Rotate in the default order. The default order is one of the following enumeration values.
:XYZ
Rotate in the X, Y, and Z order. Deprecated in Graphene 1.10, it is an alias for :SXYZ.
:YZX
Rotate in the Y, Z, and X order. Deprecated in Graphene 1.10, it is an alias for :SYZX.
:ZXY
Rotate in the Z, X, and Y order. Deprecated in Graphene 1.10, it is an alias for :SZXY.
:XZY
Rotate in the X, Z, and Y order. Deprecated in Graphene 1.10, it is an alias for :SXZY.
:YXZ
Rotate in the Y, X, and Z order. Deprecated in Graphene 1.10, it is an alias for :SYXZ.
:ZYX
Rotate in the Z, Y, and X order. Deprecated in Graphene 1.10, it is an alias for :SZYX.
:SXYZ
Defines a static rotation along the X, Y, and Z axes.
:SXYX
Defines a static rotation along the X, Y, and X axes.
:SXZY
Defines a static rotation along the X, Z, and Y axes.
:SXZX
Defines a static rotation along the X, Z, and X axes.
:SYZX
Defines a static rotation along the Y, Z, and X axes.
:SYZY
Defines a static rotation along the Y, Z, and Y axes.
:SYXZ
Defines a static rotation along the Y, X, and Z axes.
:SYXY
Defines a static rotation along the Y, X, and Y axes.
:SZXY
Defines a static rotation along the Z, X, and Y axes.
:SZXZ
Defines a static rotation along the Z, X, and Z axes.
:SZYX
Defines a static rotation along the Z, Y, and X axes.
:SZYZ
Defines a static rotation along the Z, Y, and Z axes.
:RZYX
Defines a relative rotation along the Z, Y, and X axes.
:RXYX
Defines a relative rotation along the X, Y, and X axes.
:RYZX
Defines a relative rotation along the Y, Z, and X axes.
:RXZX
Defines a relative rotation along the X, Z, and X axes.
:RXZY
Defines a relative rotation along the X, Z, and Y axes.
:RYZY
Defines a relative rotation along the Y, Z, and Y axes.
:RZXY
Defines a relative rotation along the Z, X, and Y axes.
:RYXY
Defines a relative rotation along the Y, X, and Y axes.
:RYXZ
Defines a relative rotation along the Y, X, and Z axes.
:RZXZ
Defines a relative rotation along the Z, X, and Z axes.
:RXYZ
Defines a relative rotation along the X, Y, and Z axes.
:RZYZ
Defines a relative rotation along the Z, Y, and Z axes.
Details:
Specify the order of the rotations on each axis. The :default value is special, and is used as an alias for one of the other orders.
See also:
2025-4-7
CStruct graphene:euler-t
Declaration:
(cffi:defcstruct euler-t)  
Details:
The graphene:euler-t structure defines a rotation along three axes using three angles. It also optionally can describe the order of the rotations.

Euler's rotation theorem states that, in three-dimensional space, any displacement of a rigid body such that a point on the rigid body remains fixed, is equivalent to a single rotation about some axis that runs through the fixed point. The angles on each axis can be placed in a vector of three components - α, β, and γ - called the Euler angle vector. Each rotation described by these components results in a rotation matrix:
rot(α) = A
rot(β) = B
rot(γ) = G  
The resulting rotation matrix expressed by the Euler angle vector is given by the product of each rotation matrix:
G × B × A = R  
In order to specify the meaning of an Euler angle vector, we need to assign each axis of rotation to the corresponding α, β, and γ components, for instance X, Y, and Z.

Additionally, we need to specify whether the rotations move the axes as they are applied, also known as intrinsic, or relative rotations; or if the axes stay fixed and the vectors move within the axis frame, also known as extrinsic, or static rotations. For instance, a static rotation alongside the ZYX axes will be interpreted as relative to extrinsic coordinate axes, and be performed, in order, about the Z, Y, and finally X axis. A relative rotation alongside the ZXZ axes will be interpreted as relative to intrinsic coordinate axes, and be performed, in order, about the Z axis, about the rotated X axis, and finally about the rotated Z axis.

Finally, we need to define the direction of the rotation, or the handedness of the coordinate system. In the case of Graphene, the direction is given by the right-hand rule, which means all rotations are counterclockwise.

Rotations described by Euler angles are typically immediately understandable, compared to rotations expressed using quaternions, but they are susceptible of "Gimbal lock" - the loss of one degree of freedom caused by two axis on the same plane. You typically should use the graphene:euler-t structure to expose rotation angles in your API, or to store them, but use the graphene:quaternion-t structure to apply rotations to modelview matrices, or interpolate between initial and final rotation transformations.

For more information, see:
See also:
2025-4-7
Macro graphene:with-euler ((var &rest args) &body body)
Syntax:
(graphene:with-euler (euler) body) => result
(graphene:with-euler (euler euler1) body) => result
(graphene:with-euler (euler (mat graphene:matrix-t)) body) => result
(graphene:with-euler (euler (mat graphene:matrix-t) order) body) => result
(graphene:with-euler (euler (quat graphene:quaternion-t)) body) => result
(graphene:with-euler (euler (quat graphene:quaternion-t) order) body) => result
(graphene:with-euler (euler (vec graphene:vec3-t)) body) => result
(graphene:with-euler (euler (vec graphene:vec3-t) order) body) => result
(graphene:with-euler (euler x y z) body) => result
(graphene:with-euler (euler x y z order) body) => result
(graphene:with-euler (euler (x :rad) y z) body) => result
(graphene:with-euler (euler (x :rad) y z order) body) => result
Arguments:
euler -- a graphene:euler-t instance to create and initialize
euler1 -- a graphene:euler-t instance to use for initialization
mat -- a graphene:matrix-t instance to use for initialization
quat -- a graphene:quaternion-t instance to use for initialization
vec -- a graphene:vec3-t instance to use for initialization
x, y, z -- a number coerced to a single float
order -- a graphene:euler-order-t value
Details:
The graphene:with-euler macro allocates a new graphene:euler-t instance, initializes the Euler vector with the given values and executes the body that uses the Euler vector. After execution of the body the allocated memory for the instance is released.

When no argument is given the components of the instance are initialized with zeros. The initialization from another instance is done with the graphene:euler-init-from-euler function. The initialization from other Graphene types is done with the graphene:euler-init-from-matrix, graphene:euler-init-from-quaternion and graphene:euler-init-from-vec3 functions.

The graphene:euler-init function initializes an instance with the rotation angles in degrees and the graphene:euler-init-from-radians function initializes an instance with the rotation angles in radians. In addition it is possible to initalize the order of the rotations.
Notes:
The memory is allocated with the graphene:box-alloc function and released with the graphene:box-free function.
See also:
2025-4-7
Macro graphene:with-eulers (vars &body body)
Syntax:
(graphene:with-euler (euler1 ... eulern) body) => result
Arguments:
euler1 ... eulern -- newly created graphene:euler-t instances
body -- a body that uses the bindings euler1 ... eulern
Details:
The graphene:with-eulers macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each instance can be initialized with values using the syntax for the graphene:with-euler macro. See also the graphene:with-euler documentation.
See also:
2025-4-7
Function graphene:euler-alloc ()
Returns:
The newly allocated graphene:euler-t instance.
Details:
Allocates a new graphene:euler-t instance. The contents of the returned structure are undefined.
See also:
2025-4-7
Function graphene:euler-free (euler)
Arguments:
euler -- a graphene:euler-t instance
Details:
Frees the resources allocated by the graphene:euler-alloc function.
See also:
2025-4-7
Function graphene:euler-init (euler x y z &optional order)
Arguments:
euler -- a graphene:euler-t instance
x -- a number coerced to a single float for the rotation angle on the X axis, in degrees
y -- a number coerced to a single float for the rotation angle on the Y axis, in degrees
z -- a number coerced to a single float for the rotation angle on the Z axis, in degrees
order -- an optional graphene:euler-order-t value with the order used to apply the rotations, the default value is :default
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the given angles and the given order.
See also:
2025-4-7
Function graphene:euler-init-from-matrix (euler matrix &optional order)
Arguments:
euler -- a graphene:euler-t instance
matrix -- a graphene:matrix-t instance for the rotation matrix
order -- an optional graphene:euler-order-t value for the order used to apply the rotations, the default value is :default
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the given rotation matrix. If the matrix argument is nil, the graphene:euler-t instance will be initialized with all angles set to 0.
See also:
2025-4-7
Function graphene:euler-init-from-quaternion (euler quaternion &optional order)
Arguments:
euler -- a graphene:euler-t instance
quaternion -- a normalized graphene:quaternion-t instance
order -- an optional graphene:euler-order-t value for the order used to apply the rotations, the default value is :default
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the given normalized quaternion. If the quaternion argument is nil, the graphene:euler-t instance will be initialized with all angles set to 0.
See also:
2025-4-7
Function graphene:euler-init-from-vec3 (euler vector &optional order)
Arguments:
euler -- a graphene:euler-t instance
vector -- a graphene:vec3-t instance containing the rotation angles in degrees
order -- an optional graphene:euler-order-t value for the order used to apply the rotations, the default value is :default
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the angles contained in the vector. If the vector argument is nil, the graphene:euler-t instance will be initialized with all angles set to 0.
See also:
2025-4-7
Function graphene:euler-init-from-euler (euler source)
Arguments:
euler -- a graphene:euler-t instance to initialize
source -- a graphene:euler-t instance
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the angles and order of another graphene:euler-t instance. If the source argument is nil, the graphene:euler-t instance will be initialized with all angles set to 0.
See also:
2025-4-7
Function graphene:euler-init-from-radians (euler x y z &optional order)
Arguments:
euler -- a graphene:euler-t instance
x -- a number coerced to a single float for the rotation angle on the X axis, in radians
y -- a number coerced to a single float for the rotation angle on the Y axis, in radians
z -- a number coerced to a single float for the rotation angle on the Z axis, in radians
order -- an optional graphene:euler-order-t value for the order used to apply the rotations, the default value is :default
Returns:
The initialized graphene:euler-t instance.
Details:
Initializes a graphene:euler-t instance using the given angles in radians and the optional order of rotation.
See also:
2025-4-7
Function graphene:euler-equal (a b)
Arguments:
a -- a graphene:euler-t instance
b -- another graphene:euler-t instance
Returns:
True if the two graphene:euler-t instances are equal.
Details:
Checks if two graphene:euler-t instances are equal.
See also:
2025-4-7
Function graphene:euler-x (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the rotation angle.
Details:
Retrieves the rotation angle on the X axis, in degrees.
See also:
2025-4-7
Function graphene:euler-y (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the rotation angle.
Details:
Retrieves the rotation angle on the Y axis, in degrees.
See also:
2025-4-7
Function graphene:euler-z (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the rotation angle.
Details:
Retrieves the rotation angle on the Z axis, in degrees.
See also:
2025-4-7
Function graphene:euler-order (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The graphene:euler-order-t value with the order to apply rotations.
Details:
Retrieves the order used to apply the rotations described in the graphene:euler-t instance, when converting to and from other instances, like graphene:quaternion-t and graphene:matrix-t instances. This function does not return the :default enumeration value. It will return the effective order of rotation instead.
See also:
2025-4-7
Function graphene:euler-alpha (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the first component of the Euler angle vector, in radians.
Details:
Retrieves the first component of the Euler angle vector, depending on the order of rotation. See also the graphene:euler-x function.
See also:
2025-4-7
Function graphene:euler-beta (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the second component of the Euler angle vector, in radians.
Details:
Retrieves the second component of the Euler angle vector, depending on the order of rotation. See also the graphene:euler-y function.
See also:
2025-4-7
Function graphene:euler-gamma (euler)
Arguments:
euler -- a graphene:euler-t instance
Returns:
The single float with the third component of the Euler angle vector, in radians.
Details:
Retrieves the third component of the Euler angle vector, depending on the order of rotation. See also the graphene:euler-z function.
See also:
2025-4-7
Function graphene:euler-to-vec3 (euler result)
Arguments:
euler -- a graphene:euler-t instance
result -- a graphene:vec3-t instance
Returns:
The graphene:vec3-t instance.
Details:
Retrieves the angles of a graphene:euler-t instance and initializes a graphene:vec3-t instance with them.
See also:
2025-4-7
Function graphene:euler-to-matrix (euler result)
Arguments:
euler -- a graphene:euler-t instance
result -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance.
Details:
Converts a graphene:euler-t instance into a transformation matrix expressing the extrinsic composition of rotations described by the Euler angles.

The rotations are applied over the reference frame axes in the order associated with the graphene:euler-t instance. For instance, if the order used to initialize euler is the :xyz value:
  • the first rotation moves the body around the X axis with an angle φ
  • the second rotation moves the body around the Y axis with an angle of ϑ
  • the third rotation moves the body around the Z axis with an angle of ψ
The rotation sign convention is right-handed, to preserve compatibility between Euler-based, quaternion-based, and angle-axis-based rotations.
See also:
2025-4-7
Function graphene:euler-to-quaternion (euler result)
Arguments:
euler -- a graphene:euler-t instance
result -- a graphene:quaternion-t instance
Returns:
The graphene:quaternion-t instance.
Details:
Converts a graphene:euler-t instance into a graphene:quaternion-t instance.
See also:
2025-4-7
Function graphene:euler-reorder (euler order result)
Arguments:
euler -- a graphene:euler-t instance
order -- a graphene:euler-order-t value
result -- a graphene:euler-t instance
Returns:
The graphene:euler-t instance.
Details:
Reorders a graphene:euler-t instance using order. This function is equivalent to creating a graphene:quaternion-t instance from the given graphene:euler-t instance, and then converting the quaternion into another graphene:euler-t instance.
See also:
2025-4-7

Quaternion

CStruct graphene:quaternion-t
Declaration:
(cffi:defcstruct quaternion-t)  
Details:
Quaternions are a mathematical entity that can be used to represent rotation transformations in 3D space. Unlike the usual Euler representation with roll, pitch, and yaw, quaternions do not suffer from the so-called "Gimbal Lock" problem.
See also:
2025-4-7
Macro graphene:with-quaternion ((var &rest args) &body body)
Syntax:
(graphene:with-quaternion (q) body) => result
(graphene:with-quaternion (q q1) body) => result
(graphene:with-quaternion (q (v graphene:vec4-t)) body) => result
(graphene:with-quaternion (q (m graphene:matrix-t)) body) => result
(graphene:with-quaternion (q (e graphene:euler-t)) body) => result
(graphene:with-quaternion (q angle axis) body) => result
(graphene:with-quaternion (q xdeg ydeg zdeg) body) => result
(graphene:with-quaternion (q xrad yrad zrad) body) => result
(graphene:with-quaternion (q x y z w) body) => result
Arguments:
q -- a graphene:quaternion-t instance to create and initialize
q1 -- a graphene:quaternion-t instance to use for initialization
v -- a graphene:vec4-t instance to use for initialization
e -- a graphene:euler-t instance to use for initialization
axis -- a graphene:vec3-t instance to use for initialization
angle -- a single float for the rotation on a given axis
xdeg, ydeg, zdeg -- a single float for the rotation angle, in degrees
xrad, yrad, zrad -- a single float for the rotation angle, in radians
x, y, z, w -- a single float for the component of a quaternion
Details:
The graphene:with-quaternion macro allocates a new graphene:quaternion-t instance, initializes the box with the given values and executes the body that uses the box. After execution of the body the allocated memory for the quaternion is released.
Notes:
The memory is allocated with the graphene:quaternion-alloc function and released with the graphene:quaternion-free function.
See also:
2025-4-7
Macro graphene:with-quaternions (vars &body body)
Syntax:
(graphene:with-quaternions (q1 ... qn) body) => result
Arguments:
q1 ... qn -- newly created graphene:quaternion-t instances
body -- a body that uses the bindings q1 ... qn
Details:
The graphene:with-quaternions macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each quaternion can be initialized with values using the syntax for the graphene:with-quaternion macro. See also the graphene:with-quaternion documentation.
See also:
2025-4-7
Function graphene:quaternion-alloc ()
Returns:
The newly allocated graphene:quaternion-t instance.
Details:
Allocates a new graphene:quaternion-t instance. The contents of the returned instance are undefined. Use the quaternion-free function to free the resources allocated by this function.
See also:
2025-4-7
Function graphene:quaternion-free (quaternion)
Arguments:
quaternion -- a graphene:quaternion-t instance
Details:
Frees the resources allocated by the graphene:quaternion-alloc function.
See also:
2025-4-7
Function graphene:quaternion-init (quaternion x y z w)
Arguments:
quaternion -- a graphene:quaternion-t instance
x -- a number coerced to a single float for the first component of the quaterion
y -- a number coerced to a single float for the second component of the quaterion
z -- a number coerced to a single float for the third component of the quaterion
x -- a number coerced to a single float for the fourth component of the quaterion
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the given four values.
See also:
#2025-4-7
Function graphene:quaternion-init-identity (quaternion)
Arguments:
quaternion -- a graphene:quaternion-t instance to initialize
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the identity transformation.
See also:
#2025-4-7
Function graphene:quaternion-init-from-quaternion (quaternion source)
Arguments:
quaternion -- a graphene:quaternion-t instance
source -- a graphene:quaternion-t instance
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion with the values from source.
See also:
#2025-4-7
Function graphene:quaternion-init-from-vec4 (quaternion vec)
Arguments:
quaternion -- a graphene:quaternion-t instance
vec -- a graphene:vec4-t instance
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion with the values from source.
See also:
#2025-4-7
Function graphene:quaternion-init-from-matrix (quaternion matrix)
Arguments:
quaternion -- a graphene:quaternion-t instance
matrix -- a graphene:matrix-t instance
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the rotation components of a transformation matrix.
See also:
#2025-4-7
Function graphene:quaternion-init-from-angles (quaternion xdeg ydeg zdeg)
Arguments:
quaternion -- a graphene:quaternion-t instance to initialize
xdeg -- a number coerced to a single float for the rotation angle on the X axis (yaw), in degrees
ydeg -- a number coerced to a single float for the rotation angle on the Y axis (pitch), in degrees
zdeg -- a number coerced to a single float for the rotation angle on the Z axis (roll), in degrees
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the values of the Euler angles on each axis.
See also:
#2025-4-7
Function graphene:quaternion-init-from-radians (quaternion xrad yrad zrad)
Arguments:
quaternion -- a graphene:quaternion-t instance to initalize
xrad -- a number coerced to a single float for the rotation angle on the X axis (yaw), in radians
yrad -- a number coerced to a single float for the rotation angle on the Y axis (pitch), in radians
zrad -- a number coerced to a single float for the rotation angle on the Z axis (roll), in radians
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the values of the Euler angles on each axis.
See also:
#2025-4-7
Function graphene:quaternion-init-from-angle-vec3 (quaternion angle axis)
Arguments:
quaternion -- a graphene:quaternion-t instance to initalize
angle -- a number coerced to a single float for the rotation on a given axis, in degrees
axis -- a graphene:vec3-t instance for the axis of rotation, expressed as a vector
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using an angle on a specific axis.
See also:
#2025-4-7
Function graphene:quaternion-init-from-euler (quaternion euler)
Arguments:
quaternion -- a graphene:quaternion-t instance to initialize
euler -- a graphene:euler-t instance
Returns:
The initialized graphene:quaternion-t instance.
Details:
Initializes a quaternion using the given graphene:euler-t instance.
See also:
#2025-4-7
Function graphene:quaternion-to-vec4 (quaternion result)
Arguments:
quaternion -- a graphene:quaternion-t instance
result -- a graphene:vec4-t instance
Returns:
The graphene:vec4-t instance with the components.
Details:
Copies the components of a quaternion into a graphene:vec4-t instances.
See also:
#2025-4-7
Function graphene:quaternion-to-matrix (quaternion result)
Arguments:
quaternion -- a graphene:quaternion-t instance
result -- a graphene:matrix-t instance
Returns:
The graphene:matrix-t instance.
Details:
Converts a quaternion into a transformation matrix expressing the rotation defined by the quaternion.
See also:
#2025-4-7
Function graphene:quaternion-to-angles (quaternion)
Syntax:
(graphene:quaternion-to-angles quaternion) => xdeg, ydeg, zdeg
Arguments:
quaternion -- a graphene:quaternion-t instance
Returns:
The value list of single floats with the rotation angles, in degrees.
Details:
Converts a quaternion to its corresponding rotations on the Euler angles on each axis.
See also:
#2025-4-7
Function graphene:quaternion-to-radians (quaternion)
Syntax:
(graphene:quaternion-to-angles quaternion) => xrad, yrad, zrad
Arguments:
quaternion -- a graphene:quaternion-t instance
Returns:
The value list of single floats with the rotation angles, in radians.
Details:
Converts a quaternion to its corresponding rotations on the Euler angles on each axis.
See also:
#2025-4-7
Function graphene:quaternion-to-angle-vec3 (quaternion axis)
Syntax:
(graphene:quaternion-to-angle-vec3 quaterion result) => angle, result
Arguments:
quaternion -- a graphene:quaternion-t instance
result -- a graphene:vec3-t instance for the rotation axis
Returns:
The value list with the angle in degrees and the graphene:vec3-t instance with the rotation axis.
Details:
Converts a quaternion into an angle and an axis pair.
See also:
#2025-4-7
Function graphene:quaternion-equal (a b)
Arguments:
a -- a graphene:quaternion-t instance
b -- a graphene:quaternion-t instance
Returns:
True if the quaternions are equal.
Details:
Checks whether the given quaternions are equal.
See also:
#2025-4-7
Function graphene:quaternion-dot (a b)
Arguments:
a -- a graphene:quaternion-t instance
b -- a graphene:quaternion-t instance
Returns:
The single float with the value of the dot product.
Details:
Computes the dot product of two quaternions.
See also:
#2025-4-7
Function graphene:quaternion-invert (quaternion result)
Arguments:
quaternion -- a graphene:quaternion-t instance
result -- a graphene:quaternion-t instance for the result
Returns:
The graphene:quaternion-t instance with the inverted quaternion.
Details:
Inverts a quaternion and returns the conjugate quaternion.
See also:
#2025-4-7
Function graphene:quaternion-normalize (quaternion result)
Arguments:
quaternion -- a graphene:quaternion-t instance
result -- a graphene:quaternion-t instance for the normalized quaternion
Returns:
The normalized graphene:quaternion-t instance.
Details:
Normalizes a quaternion.
See also:
#2025-4-7
Function graphene:quaternion-add (a b result)
Arguments:
a -- a graphene:quaternion-t instance
b -- a graphene:quaternion-t instance
result -- a graphene:quaternion-t instance for the result
Returns:
The graphene:quaternion-t instance with the result.
Details:
Adds two quaternions a and b.
See also:
#2025-4-7
Function graphene:quaternion-multiply (a b result)
Arguments:
a -- a graphene:quaternion-t instance
b -- a graphene:quaternion-t instance
result -- a graphene:quaternion-t instance for the result
Returns:
The graphene:quaternion-t instance with the result.
Details:
Multiplies two quaternions a and b.
See also:
#2025-4-7
Function graphene:quaternion-scale (quaternion factor result)
Arguments:
quaternion -- a graphene:quaternion-t instance
factor -- a number coerced to a single float for the scaling factor
result -- a graphene:quaternion-t instance for the result
Returns:
The graphene:quaternion-t instance with the result.
Details:
Scales all the elements of a quaternion using the given scalar factor.
See also:
#2025-4-7
Function graphene:quaternion-slerp (a b factor result)
Arguments:
a -- a graphene:quaternion-t instance
b -- a graphene:quaternion-t instance
factor -- a number coerced to a single float for the interpolation factor
result -- a graphene:quaternion-t instance for the result
Details:
The graphene:quaternion-t instance with the interpolated quaternion.
See also:
#2025-4-7

Plane

CStruct graphene:plane-t
Declaration:
(cffi:defcstruct plane-t
  (normal :float :count 4)
  (constant :float :count 4))  
Details:
The graphene:plane-t structure is a structure representing a plane that extends infinitely in 3D space. The plane is described using the Hessian normal form of a unit length normal vector pointing towards the origin, and a constant distance from the origin along the normal vector.
2025-4-7
Macro graphene:with-plane ((var &rest args) &body body)
Syntax:
(graphene:with-plane (plane) body) => result
(graphene:with-plane (plane plane1) body) => result
(graphene:with-plane (plane (v graphene:vec4-t) body) => result
(graphene:with-plane (plane normal constant) body) => result
(graphene:with-plane (plane normal (point graphene:point3d-t)) body) => result
(graphene:with-plane (plane a b c) body) => result
Arguments:
plane -- a graphene:plane-t instance to create and initialize
plane1 -- a graphene:plane-t instance to use for initialization
v -- a graphene:vec4-t instance to use for initialization
normal -- a graphene:vec3-t instance to use for initialization
point -- a graphene:point3d-t instance to use for initialization
a, b, c -- a graphene:point3d-t instance
constant -- a single float
Details:
The graphene:with-plane macro allocates a new graphene:plane-t instance, initializes the box with the given values and executes the body that uses the box. After execution of the body the allocated memory for the plane is released.
Notes:
The memory is allocated with the graphene:plane-alloc function and released with the graphene:plane-free function.
See also:
2025-4-7
Macro graphene:with-planes (vars &body body)
Syntax:
(graphene:with-planes (plane1 ... planen) body) => result
Arguments:
plane1 ... planen -- newly created graphene:plane-t instances
body -- a body that uses the bindings plane1 ... planen
Details:
The graphene:with-planes macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each plane can be initialized with values using the syntax for the graphene:with-plane macro. See also the graphene:with-plane documentation.
See also:
2025-4-7
Function graphene:plane-alloc ()
Returns:
The newly allocated graphene:plane-t instance.
Details:
Allocates a new graphene:plane-t instance. The contents of the returned instance are undefined. Use the graphene:plane-free function to free the resources allocated by this function.
See also:
2025-4-7
Function graphene:plane-free (plane)
Arguments:
plane -- a graphene:plane-t instance
Details:
Frees the resources allocated by the graphene:plane-alloc function.
See also:
2025-4-7
Function graphene:plane-init (plane normal constant)
Arguments:
plane -- a graphene:plane-t instance to initialize
normal -- a graphene:vec3-t instance for a unit length normal vector defining the plane pointing towards the origin, if unset, the X axis is used by default
constant -- a number coerced to a single float for the distance from the origin to the plane along the normal vector, the sign determines the half-space occupied by the plane
Returns:
The initialized graphene:plane-t instance.
Details:
Initializes the given plane using the given normal vector and constant value.
See also:
2025-4-7
Function graphene:plane-init-from-vec4 (plane vector)
Arguments:
plane -- a graphene:plane-t instance to initialize
vector -- a graphene:vec4-t instance for the vector containing the normal vector in its first three components, and the distance in its fourth component
Returns:
The initialized graphene:plane-t instance.
Details:
Initializes the given plane using the components of the given vector.
See also:
2025-4-7
Function graphene:plane-init-from-plane (plane source)
Arguments:
plane -- a graphene:plane-t instance to initialize
source -- a graphene:plane-t instance
Returns:
The initialized graphene:plane-t instance.
Details:
Initializes the given plane using the normal vector and constant of another plane.
See also:
#2025-4-7
Function graphene:plane-init-from-point (plane normal point)
Arguments:
plane -- a graphene:plane-t instance to initialize
normal -- a graphene:vec3-t instance for the normal vector defining the plane pointing towards the origin
point -- a point3d-t instance
Returns:
The initialized graphene:plane-t instance.
Details:
Initializes the given plane using the given normal vector and an arbitrary co-planar point.
See also:
#2025-4-7
Function graphene:plane-init-from-points (plane a b c)
Arguments:
plane -- a graphene:plane-t instance to initialize
a -- a graphene:point3d-t instance
b -- a graphene:point3d-t instance
c -- a graphene:point3d-t instance
Returns:
The initialized graphene:plane-t instance.
Details:
Initializes the given plane using the 3 provided co-planar points. The winding order is counter-clockwise, and determines which direction the normal vector will point.
See also:
#2025-4-7
Function graphene:plane-normalize (plane result)
Arguments:
plane -- a graphene:plane-t instance to initialize
result -- a graphene:plane-t instance for the result
Returns:
The normalized graphene:plane-t instance.
Details:
Normalizes the vector of the given plane, and adjusts the constant accordingly.
See also:
#2025-4-7
Function graphene:plane-negate (plane result)
Arguments:
plane -- a graphene:plane-t instance to initialize
result -- a graphene:plane-t instance for the result
Returns:
The normalized graphene:plane-t instance.
Details:
Negates the normal vector and constant of the plane, effectively mirroring the plane across the origin.
See also:
#2025-4-7
Function graphene:plane-equal (a b)
Arguments:
a -- a graphene:plane-t instance
b -- a graphene:plane-t instance
Returns:
True if the given planes are equal.
Details:
Checks whether the two given planes are equal.
See also:
#2025-4-7
Function graphene:plane-distance (plane point)
Arguments:
plane -- a graphene:plane-t instance
point -- a graphene:point3d-t instance
Returns:
The single float with the distance of the given point from the plane.
Details:
Computes the distance of the point from the plane.
See also:
#2025-4-7
Function graphene:plane-transform (plane matrix normal result)
Arguments:
plane -- a graphene:plane-t instance
matrix -- a graphene:matrix-t instance
normal -- a graphene:matrix-t instance
result -- a graphene:plane-t instance
Returns:
The transformed graphene:plane-t instance.
Details:
Transforms a plane using the given matrix and normal matrix. If the normal matrix is nil, a transformation matrix for the plane normal will be computed from matrix. If you are transforming multiple planes using the same matrix it is recommended to compute the normal matrix beforehand to avoid incurring in the cost of recomputing it every time.
See also:
#2025-4-7
Function graphene:plane-normal (plane normal)
Arguments:
plane -- a graphene:plane-t instance
normal -- a graphene:vec3-t instance for the normal vector
Returns:
The graphene:vec3-t instance with the normal vector.
Details:
Retrieves the normal vector pointing towards the origin of the given plane.
See also:
2025-4-7
Function graphene:plane-constant (plane)
Arguments:
plane -- a graphene:plane-t instance
Returns:
The single float with the constant value of the plane.
Details:
Retrieves the distance along the normal vector of the given plane from the origin.
See also:
2025-4-7

Ray

CEnum graphene:ray-intersection-kind-t
Declaration:
(cffi:defcenum ray-intersection-kind-t
  :none
  :enter
  :leave)  
Values:
:none
No intersection.
:enter
The ray is entering the intersected object.
:leave
The ray is leaving the intersected object.
Details:
The type of intersection.
See also:
#2025-4-7
CStruct graphene:ray-t
Declaration:
(cffi:defcstruct ray-t)  
Details:
The graphene:ray-t structure is a structure representing a ray emitted by an origin, identified by a point in 3D space, in a given direction, identified by a vector with 3 components.

A common use of the graphene:ray-t implementation is ray-casting to find which objects in a 3D scene are under the coordinates of the pointer.
2025-4-7
Macro graphene:with-ray ((var &rest args) &body body)
Syntax:
(graphene:with-ray (ray) body) => result
(graphene:with-ray (ray ray1) body) => result
(graphene:with-ray (ray origin direction) body) => result
(graphene:with-ray (ray (origin graphene:vec3-t) direction) body) => result
Arguments:
ray -- a graphene:ray-t instance to create and initialize
ray1 -- a graphene:ray-t instance to use for initialization
origin -- a graphene:point3d-t or a graphene:vec3-t instance to use for initialization
direction -- a graphene:vec3-t instance to use for initialization
Details:
The graphene:with-ray macro allocates a new graphene:ray-t instance, initializes the box with the given values and executes the body that uses the ray. After execution of the body the allocated memory for the box is released.
Notes:
The memory is allocated with the graphene:ray-alloc function and released with the graphene:ray-free function.
See also:
2025-4-7
Macro graphene:with-rays (vars &body body)
Syntax:
(graphene:with-rays (ray1 ... rayn) body) => result
Arguments:
ray1 ... rayn -- newly created graphene:ray-t instances
body -- a body that uses the bindings ray1 ... rayn
Details:
The graphene:with-rays macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each ray can be initialized with values using the syntax for the graphene:with-ray macro. See also the graphene:with-ray documentation.
See also:
2025-4-7
Function graphene:ray-alloc ()
Returns:
The newly allocated graphene:ray-t instance.
Details:
Allocates a new graphene:ray-t instance. The contents of the returned structure are undefined. Use the graphene:ray-free function to free the resources allocated by this function.
See also:
2025-4-7
Function graphene:ray-free (ray)
Arguments:
ray -- a graphene:ray-t instance
Details:
Frees the resources allocated by the graphene:ray-alloc function.
See also:
2025-4-7
Function graphene:ray-init (ray origin direction)
Arguments:
ray -- a graphene:ray-t instance to be initialized
origin -- a graphene:point3d-t instance for the origin of the ray
direction -- a graphene:vec3-t instance for the direction vector
Returns:
The initialized graphene:ray-t instance.
Details:
Initializes the given graphene:ray-t instance using the given origin and direction values. The direction vector is normalized.
See also:
2025-4-7
Function graphene:ray-init-from-ray (ray source)
Arguments:
ray -- a graphene:ray-t instance to initialize
source -- a graphene:ray-t instance
Returns:
The initialized graphene:ray-t instance.
Details:
Initializes the given ray using the origin and direction values of another ray.
See also:
2025-4-7
Function graphene:ray-init-from-vec3 (ray origin direction)
Arguments:
ray -- a graphene:ray-t instance to initialize
origin -- a graphene:vec3-t instance
direction -- a graphene:vec3-t_instance
Returns:
The initialized graphene:ray-t instance.
Details:
Initializes the given ray using the given vectors.
See also:
2025-4-7
Function graphene:ray-origin (ray origin)
Arguments:
ray -- a graphene:ray-t instance
origin -- a graphene:point3d-t instance for the origin
Returns:
The graphene:point3d-t instance with the origin.
Details:
Retrieves the origin of the given ray.
See also:
2025-4-7
Function graphene:ray-direction (ray direction)
Arguments:
ray -- a graphene:ray-t instance
direction -- a graphene:vec3-t instance for the direction
Returns:
The graphene:vec3-t instance with the direction.
Details:
Retrieves the direction of the given ray.
See also:
2025-4-7
Function graphene:ray-position-at (ray parameter pos)
Arguments:
ray -- a graphene:ray-t instance
parameter -- a number coerced to a single float for the distance along the ray
pos -- a graphene:point3d-t instance for the position
Returns:
The graphene:point3d-t instance with the position
Details:
Retrieves the coordinates of a point at the distance parameter along the given ray.
See also:
2025-4-7
Function graphene:ray-distance-to-point (ray point)
Arguments:
ray -- a graphene:ray-t instance
point -- a graphene:point3d-t instance
Returns:
The single float with the distance of the point.
Details:
Computes the distance of the closest approach between the given ray and the point. The closest approach to a ray from a point is the distance between the point and the projection of the point on the ray itself.
See also:
2025-4-7
Function graphene:ray-distance-to-plane (ray plane)
Arguments:
ray -- a graphene:ray-t instance
plane -- a graphene:plane-t instance
Returns:
The single float with the distance of the origin of the ray from the plane.
Details:
Computes the distance of the origin of the given ray from the given plane. If the ray does not intersect the plane, this function returns INFINITY.
See also:
#2025-4-7
Function graphene:ray-closest-point-to-point (ray point result)
Arguments:
ray -- a graphene:ray-t instance
point -- a graphene:point3d-t instance
result -- a graphene:point3d-t instance for the result
Returns:
The graphene:point3d-t instance with the closest point.
Details:
Computes the point on the given ray that is closest to the given point.
See also:
#2025-4-7
Function graphene:ray-equal (a b)
Arguments:
a -- a graphene:ray-t instance
b -- a graphene:ray-t instance
Returns:
True if the given are equal.
Details:
Checks whether the two given rays are equal.
See also:
#2025-4-7
Function graphene:ray-intersect-sphere (ray sphere)
Arguments:
ray -- a graphene:ray-t instance
sphere -- a graphene:sphere-t instance
Returns:
kind -- a graphene:ray-intersection-kind-t value
dist -- a single float with the distance of the point on the ray that intersects the sphere
Details:
Intersects the given ray with the given sphere.
See also:
2025-4-7
Function graphene:ray-intersects-sphere (ray sphere)
Arguments:
ray -- a graphene:ray-t instance
sphere -- a graphene:sphere-t instance
Returns:
True if the ray intersects the sphere.
Details:
Checks if the given ray intersects the given sphere.
See also:
2025-4-7
Function graphene:ray-intersect-box (ray box)
Arguments:
ray -- a graphene:ray-t instance
box -- a graphene:box-t instance
Returns:
kind -- a graphene:ray-intersection-kind-t value
dist -- a single float with the distance of the point on the ray that intersects the box
Details:
Intersects the given ray with the given box.
See also:
#2025-4-7
Function graphene:ray-intersects-box (ray box)
Arguments:
ray -- a graphene:ray-t instance
box -- a graphene:box-t instance
Returns:
True if the ray intersects the box.
Details:
Checks if the given ray intersects the given box.
See also:
#2025-4-7
Function graphene:ray-intersect-triangle (ray triangle)
Arguments:
ray -- a graphene:ray-t instance
box -- a graphene:triangle-t instance
Returns:
kind -- a graphene:ray-intersection-kind-t value
dist -- a single float with the distance of the point on the ray that intersects the triangle
Details:
Intersects the given ray with the given triangle.
See also:
#2025-4-7
Function graphene:ray-intersects-triangle (ray triangle)
Arguments:
ray -- a graphene:ray-t instance
box -- a graphene:triangle-t instance
Returns:
True if the ray intersects the triangle.
Details:
Checks if the given ray intersects the given triangle.
See also:
#2025-4-7

Other Macros in graphene

Macro graphene:with-object ((var type &rest args) &body body)
Syntax:
(graphene:with-object (obj type &rest args) body) => result
Arguments:
obj -- a Graphene instance to create and initialize
type -- a symbol for a Graphene type
args -- arguments for initializing the Graphene instance
Details:
The graphene:with-object macro allocates an new Graphene instance for the given Graphene type, initializes the Graphene instance with given values and executes the body that uses the Graphene instance. After execution of the body the allocated memory for the Graphene instance is released.

The type argument can have one of the following values to create and initialize a corresponding Graphene instance:
graphene:point-t
See the graphene:with-point macro.
graphene:point3d-t
See the graphene:with-point3d macro.
graphene:size-t
See the graphene:with-size macro.
graphene:rect-t
See the graphene:with-rect macro.
graphene:quad-t
See the graphene:with-quad macro.
graphene:triangle-t
See the graphene:with-triangle macro.
graphene:box-t
See the graphene:with-box macro.
graphene:sphere-t
See the graphene:with-sphere macro.
graphene:frustum-t
See the graphene:with-frustum macro.
graphene:vec2-t
See the graphene:with-vec2 macro.
graphene:vec3-t
See the graphene:with-vec3 macro.
graphene:vec4-t
See the graphene:with-vec4 macro.
graphene:matrix-t
See the graphene:with-matrix macro.
graphene:euler-t
See the graphene:with-euler macro.
graphene:quaternion-t
See the graphene:with-quaternion macro.
graphene:plane-t
See the graphene:with-plane macro.
graphene:ray-t
See the graphene:with-ray macro.
Examples:
Initalize a graphene:point-t instance with default values:
* (macroexpand '(graphene:with-object (p graphene:point-t) p))
(LET ((P (GRAPHENE:POINT-ALLOC)))
  (GRAPHENE:POINT-INIT P 0.0 0.0)
  (UNWIND-PROTECT (PROGN P) (GRAPHENE:POINT-FREE P)))
T    
Initialize a graphene:with-point instance with two values:
* (macroexpand '(graphene:with-object (p graphene:point-t 1 2) p))
(LET ((P (GRAPHENE:POINT-ALLOC)))
  (GRAPHENE:POINT-INIT P 1 2)
  (UNWIND-PROTECT (PROGN P) (GRAPHENE:POINT-FREE P)))
T    
See also:
2025-4-7
Macro graphene:with-objects (vars &body body)
Syntax:
(graphene:with-objects (obj1 ... objn) body) => result
Arguments:
obj1 ... objn -- newly created Graphene instances
body -- a body that uses the bindings obj1 ... objn
Details:
The graphene:with-objects macro creates new variable bindings and executes the body that use these bindings. The macro performs the bindings sequentially, like the let* macro.

Each object can be initialized with values using the syntax for the graphene:with-object macro. See also the graphene:with-object documentation.
See also:
2025-4-7

Index of Exported Symbols

cairo:antialias, Function
cairo:append-path, Function
cairo:arc, Function
cairo:arc-negative, Function
cairo:clip, Function
cairo:clip-extents, Function
cairo:clip-preserve, Function
cairo:close-path, Function
cairo:copy-clip-rectangle-list, Function
cairo:copy-page, Function
cairo:copy-path, Function
cairo:copy-path-flat, Function
cairo:create, Function
cairo:current-point, Function
cairo:curve-to, Function
cairo:dash, Function
cairo:dash-count, Function
cairo:destroy, Function
cairo:device-acquire, Function
cairo:device-destroy, Function
cairo:device-finish, Function
cairo:device-flush, Function
cairo:device-reference, Function
cairo:device-reference-count, Function
cairo:device-release, Function
cairo:device-status, Function
cairo:device-to-user, Function
cairo:device-to-user-distance, Function
cairo:device-type, Function
cairo:fill, Function
cairo:fill-extents, Function
cairo:fill-preserve, Function
cairo:fill-rule, Function
cairo:font-extents, Function
cairo:font-face, Function
cairo:font-face-destroy, Function
cairo:font-face-reference, Function
cairo:font-face-reference-count, Function
cairo:font-face-status, Function
cairo:font-face-type, Function
cairo:font-matrix, Function
cairo:font-options, Function
cairo:font-options-antialias, Function
cairo:font-options-color-mode, Function
cairo:font-options-color-palette, Function
cairo:font-options-copy, Function
cairo:font-options-create, Function
cairo:font-options-custom-palette-color, Function
cairo:font-options-destroy, Function
cairo:font-options-equal, Function
cairo:font-options-hash, Function
cairo:font-options-hint-metrics, Function
cairo:font-options-hint-style, Function
cairo:font-options-merge, Function
cairo:font-options-status, Function
cairo:font-options-subpixel-order, Function
cairo:font-options-variations, Function
cairo:format-stride-for-width, Function
cairo:glyph-extents, Function
cairo:glyph-path, Function
cairo:group-target, Function
cairo:hairline, Function
cairo:has-current-point, Function
cairo:identity-matrix, Function
cairo:image-surface-create, Function
cairo:image-surface-create-for-data, Function
cairo:image-surface-create-from-png, Function
cairo:image-surface-data, Function
cairo:image-surface-format, Function
cairo:image-surface-height, Function
cairo:image-surface-stride, Function
cairo:image-surface-width, Function
cairo:in-clip, Function
cairo:in-fill, Function
cairo:in-stroke, Function
cairo:line-cap, Function
cairo:line-join, Function
cairo:line-to, Function
cairo:line-width, Function
cairo:mask, Function
cairo:mask-surface, Function
cairo:matrix, Function
cairo:matrix-init, Function
cairo:matrix-init-identity, Function
cairo:matrix-init-rotate, Function
cairo:matrix-init-scale, Function
cairo:matrix-init-translate, Function
cairo:matrix-invert, Function
cairo:matrix-multiply, Function
cairo:matrix-rotate, Function
cairo:matrix-scale, Function
cairo:matrix-to-float, Function
cairo:matrix-transform-distance, Function
cairo:matrix-transform-point, Function
cairo:matrix-translate, Function
cairo:mesh-pattern-begin-patch, Function
cairo:mesh-pattern-control-point, Function
cairo:mesh-pattern-corner-color-rgba, Function
cairo:mesh-pattern-curve-to, Function
cairo:mesh-pattern-end-patch, Function
cairo:mesh-pattern-line-to, Function
cairo:mesh-pattern-move-to, Function
cairo:mesh-pattern-patch-count, Function
cairo:mesh-pattern-path, Function
cairo:mesh-pattern-set-control-point, Function
cairo:mesh-pattern-set-corner-color-rgb, Function
cairo:mesh-pattern-set-corner-color-rgba, Function
cairo:miter-limit, Function
cairo:move-to, Function
cairo:new-path, Function
cairo:new-sub-path, Function
cairo:operator, Function
cairo:paint, Function
cairo:paint-with-alpha, Function
cairo:path-data, Accessor
cairo:path-data-to-list, Function
cairo:path-destroy, Function
cairo:path-extents, Function
cairo:path-numdata, Accessor
cairo:path-status, Accessor
cairo:pattern-add-color-stop-rgb, Function
cairo:pattern-add-color-stop-rgba, Function
cairo:pattern-color-stop-count, Function
cairo:pattern-color-stop-rgba, Function
cairo:pattern-create-for-surface, Function
cairo:pattern-create-linear, Function
cairo:pattern-create-mesh, Function
cairo:pattern-create-radial, Function
cairo:pattern-create-rgb, Function
cairo:pattern-create-rgba, Function
cairo:pattern-destroy, Function
cairo:pattern-extend, Function
cairo:pattern-filter, Function
cairo:pattern-linear-points, Function
cairo:pattern-matrix, Function
cairo:pattern-radial-circles, Function
cairo:pattern-reference, Function
cairo:pattern-reference-count, Function
cairo:pattern-rgba, Function
cairo:pattern-status, Function
cairo:pattern-surface, Function
cairo:pattern-type, Function
cairo:pdf-surface-add-outline, Function
cairo:pdf-surface-create, Function
cairo:pdf-surface-restrict-to-version, Function
cairo:pdf-surface-set-custom-metadata, Function
cairo:pdf-surface-set-metadata, Function
cairo:pdf-surface-set-page-label, Function
cairo:pdf-surface-set-size, Function
cairo:pdf-surface-set-thumbnail-size, Function
cairo:pdf-version-to-string, Function
cairo:pdf-versions, Function
cairo:pop-group, Function
cairo:pop-group-to-source, Function
cairo:ps-level-to-string, Function
cairo:ps-levels, Function
cairo:ps-surface-create, Function
cairo:ps-surface-dsc-begin-page-setup, Function
cairo:ps-surface-dsc-begin-setup, Function
cairo:ps-surface-dsc-comment, Function
cairo:ps-surface-eps, Function
cairo:ps-surface-restrict-to-level, Function
cairo:ps-surface-set-size, Function
cairo:push-group, Function
cairo:push-group-with-content, Function
cairo:recording-surface-create, Function
cairo:recording-surface-extents, Function
cairo:recording-surface-ink-extents, Function
cairo:rectangle, Function
cairo:reference, Function
cairo:reference-count, Function
cairo:region-contains-point, Function
cairo:region-contains-rectangle, Function
cairo:region-copy, Function
cairo:region-create, Function
cairo:region-create-rectangle, Function
cairo:region-create-rectangles, Function
cairo:region-destroy, Function
cairo:region-equal, Function
cairo:region-extents, Function
cairo:region-intersect, Function
cairo:region-intersect-rectangle, Function
cairo:region-is-empty, Function
cairo:region-num-rectangles, Function
cairo:region-rectangle, Function
cairo:region-reference, Function
cairo:region-status, Function
cairo:region-subtract, Function
cairo:region-subtract-rectangle, Function
cairo:region-translate, Function
cairo:region-union, Function
cairo:region-union-rectangle, Function
cairo:region-xor, Function
cairo:region-xor-rectangle, Function
cairo:rel-curve-to, Function
cairo:rel-line-to, Function
cairo:rel-move-to, Function
cairo:reset-clip, Function
cairo:restore, Function
cairo:rotate, Function
cairo:save, Function
cairo:scale, Function
cairo:scaled-font, Function
cairo:scaled-font-create, Function
cairo:scaled-font-ctm, Function
cairo:scaled-font-destroy, Function
cairo:scaled-font-extents, Function
cairo:scaled-font-font-face, Function
cairo:scaled-font-font-matrix, Function
cairo:scaled-font-font-options, Function
cairo:scaled-font-glyph-extents, Function
cairo:scaled-font-reference, Function
cairo:scaled-font-reference-count, Function
cairo:scaled-font-scale-matrix, Function
cairo:scaled-font-status, Function
cairo:scaled-font-text-extents, Function
cairo:scaled-font-text-to-glyphs, Function
cairo:scaled-font-type, Function
cairo:script-create, Function
cairo:script-from-recording-surface, Function
cairo:script-mode, Function
cairo:script-surface-create, Function
cairo:script-surface-create-for-target, Function
cairo:script-write-comment, Function
cairo:select-font-face, Function
cairo:set-font-size, Function
cairo:set-source-rgb, Function
cairo:set-source-rgba, Function
cairo:set-source-surface, Function
cairo:show-glyphs, Function
cairo:show-page, Function
cairo:show-text, Function
cairo:source, Function
cairo:status, Function
cairo:status-to-string, Function
cairo:stroke, Function
cairo:stroke-extents, Function
cairo:stroke-preserve, Function
cairo:surface-content, Function
cairo:surface-copy-page, Function
cairo:surface-create-for-rectangle, Function
cairo:surface-create-similar, Function
cairo:surface-create-similar-image, Function
cairo:surface-destroy, Function
cairo:surface-device, Function
cairo:surface-device-offset, Function
cairo:surface-device-scale, Function
cairo:surface-fallback-resolution, Function
cairo:surface-finish, Function
cairo:surface-flush, Function
cairo:surface-font-options, Function
cairo:surface-mark-dirty, Function
cairo:surface-mark-dirty-rectangle, Function
cairo:surface-reference, Function
cairo:surface-reference-count, Function
cairo:surface-show-page, Function
cairo:surface-status, Function
cairo:surface-type, Function
cairo:surface-write-to-png, Function
cairo:svg-surface-create, Function
cairo:svg-surface-document-unit, Function
cairo:svg-surface-restrict-to-version, Function
cairo:svg-version-to-string, Function
cairo:svg-versions, Function
cairo:target, Function
cairo:text-extents, Function
cairo:text-path, Function
cairo:tolerance, Function
cairo:toy-font-face-create, Function
cairo:toy-font-face-family, Function
cairo:toy-font-face-slant, Function
cairo:toy-font-face-weight, Function
cairo:transform, Function
cairo:translate, Function
cairo:user-to-device, Function
cairo:user-to-device-distance, Function
cairo:version, Function
cairo:version-encode, Function
cairo:version-string, Function
cairo:with-context, Macro
cairo:with-context-for-image-surface, Macro
cairo:with-context-for-pdf-surface, Macro
cairo:with-context-for-recording-surface, Macro
cairo:with-context-for-surface, Macro
cairo:with-image-surface, Macro
cairo:with-matrices, Macro
cairo:with-matrix, Macro
cairo:with-pdf-surface, Macro
cairo:with-ps-surface, Macro
cairo:with-recording-surface, Macro
cairo:with-scaled-font, Macro
cairo:with-script-surface, Macro
cairo:with-surface, Macro
cairo:with-toy-font-face, Macro
cairo:antialias-t, CEnum
cairo:color-mode-t, CEnum
cairo:content-t, CEnum
cairo:context-t, CStruct
cairo:device-t, CStruct
cairo:device-type-t, CEnum
cairo:extend-t, CEnum
cairo:fill-rule-t, CEnum
cairo:filter-t, CEnum
cairo:font-extents-t, CStruct
cairo:font-face-t, CStruct
cairo:font-options-t, CStruct
cairo:font-slant-t, CEnum
cairo:font-type-t, CEnum
cairo:font-weight-t, CEnum
cairo:format-t, CEnum
cairo:glyph-t, CStruct
cairo:hint-metrics-t, CEnum
cairo:hint-style-t, CEnum
cairo:line-cap-t, CEnum
cairo:line-join-t, CEnum
cairo:matrix-t, CStruct
cairo:operator-t, CEnum
cairo:path-data-t, CStruct
cairo:path-data-type-t, CEnum
cairo:path-t, CStruct
cairo:pattern-t, CStruct
cairo:pattern-type-t, CEnum
cairo:pdf-metadata-t, CEnum
cairo:pdf-outline-flags-t, Bitfield
cairo:pdf-version-t, CEnum
cairo:ps-level-t, CEnum
cairo:region-overlap-t, Enum
cairo:region-t, CStruct
cairo:scaled-font-t, CStruct
cairo:script-mode-t, CEnum
cairo:status-t, CEnum
cairo:subpixel-order-t, CEnum
cairo:surface-t, CStruct
cairo:surface-type-t, CEnum
cairo:svg-unit-t, CEnum
cairo:svg-version-t, CEnum
cairo:text-extents-t, CStruct
gdk-pixbuf:pixbuf, Class
gdk-pixbuf:pixbuf-animation, Class
gdk-pixbuf:pixbuf-animation-iter, Class
gdk-pixbuf:pixbuf-loader, Class
gdk-pixbuf:pixbuf-simple-anim, Class
gdk-pixbuf:pixbuf-add-alpha, Function
gdk-pixbuf:pixbuf-animation-height, Function
gdk-pixbuf:pixbuf-animation-is-static-image, Function
gdk-pixbuf:pixbuf-animation-iter, Function
gdk-pixbuf:pixbuf-animation-iter-advance, Function
gdk-pixbuf:pixbuf-animation-iter-delay-time, Function
gdk-pixbuf:pixbuf-animation-iter-on-currently-loading-frame, Function
gdk-pixbuf:pixbuf-animation-iter-pixbuf, Function
gdk-pixbuf:pixbuf-animation-new-from-file, Function
gdk-pixbuf:pixbuf-animation-new-from-resource, Function
gdk-pixbuf:pixbuf-animation-static-image, Function
gdk-pixbuf:pixbuf-animation-width, Function
gdk-pixbuf:pixbuf-bits-per-sample, Accessor
gdk-pixbuf:pixbuf-byte-length, Function
gdk-pixbuf:pixbuf-colorspace, Accessor
gdk-pixbuf:pixbuf-composite, Function
gdk-pixbuf:pixbuf-composite-color, Function
gdk-pixbuf:pixbuf-composite-color-simple, Function
gdk-pixbuf:pixbuf-copy, Function
gdk-pixbuf:pixbuf-copy-area, Function
gdk-pixbuf:pixbuf-copy-options, Function
gdk-pixbuf:pixbuf-file-info, Function
gdk-pixbuf:pixbuf-file-info-async, Function
gdk-pixbuf:pixbuf-file-info-finish, Function
gdk-pixbuf:pixbuf-fill, Function
gdk-pixbuf:pixbuf-flip, Function
gdk-pixbuf:pixbuf-format-description, Function
gdk-pixbuf:pixbuf-format-extensions, Function
gdk-pixbuf:pixbuf-format-is-disabled, Function
gdk-pixbuf:pixbuf-format-is-save-option-supported, Function
gdk-pixbuf:pixbuf-format-is-scalable, Function
gdk-pixbuf:pixbuf-format-is-writable, Function
gdk-pixbuf:pixbuf-format-license, Function
gdk-pixbuf:pixbuf-format-mime-types, Function
gdk-pixbuf:pixbuf-format-name, Function
gdk-pixbuf:pixbuf-format-set-disabled, Function
gdk-pixbuf:pixbuf-formats, Function
gdk-pixbuf:pixbuf-has-alpha, Accessor
gdk-pixbuf:pixbuf-height, Accessor
gdk-pixbuf:pixbuf-loader-animation, Function
gdk-pixbuf:pixbuf-loader-close, Function
gdk-pixbuf:pixbuf-loader-new, Function
gdk-pixbuf:pixbuf-loader-pixbuf, Function
gdk-pixbuf:pixbuf-loader-set-size, Function
gdk-pixbuf:pixbuf-loader-write, Function
gdk-pixbuf:pixbuf-n-channels, Accessor
gdk-pixbuf:pixbuf-new, Function
gdk-pixbuf:pixbuf-new-from-bytes, Function
gdk-pixbuf:pixbuf-new-from-file, Function
gdk-pixbuf:pixbuf-new-from-file-at-scale, Function
gdk-pixbuf:pixbuf-new-from-file-at-size, Function
gdk-pixbuf:pixbuf-new-from-resource, Function
gdk-pixbuf:pixbuf-new-from-resource-at-scale, Function
gdk-pixbuf:pixbuf-new-subpixbuf, Function
gdk-pixbuf:pixbuf-option, Function
gdk-pixbuf:pixbuf-pixel-bytes, Accessor
gdk-pixbuf:pixbuf-pixels, Accessor
gdk-pixbuf:pixbuf-pixels-with-length, Function
gdk-pixbuf:pixbuf-read-pixels, Function
gdk-pixbuf:pixbuf-remove-option, Function
gdk-pixbuf:pixbuf-rotate-simple, Function
gdk-pixbuf:pixbuf-rowstride, Accessor
gdk-pixbuf:pixbuf-save, Function
gdk-pixbuf:pixbuf-scale, Function
gdk-pixbuf:pixbuf-scale-simple, Function
gdk-pixbuf:pixbuf-simple-anim-add-frame, Function
gdk-pixbuf:pixbuf-simple-anim-loop, Accessor
gdk-pixbuf:pixbuf-simple-anim-new, Function
gdk-pixbuf:pixbuf-width, Accessor
gdk-pixbuf:+major-version+, Constant
gdk-pixbuf:+micro-version+, Constant
gdk-pixbuf:+minor-version+, Constant
gdk-pixbuf:+version+, Constant
gdk-pixbuf:colorspace, GEnum
gdk-pixbuf:pixbuf-format, CStruct
gdk-pixbuf:pixbuf-interp-type, GEnum
gdk-pixbuf:pixbuf-rotation, GEnum
gdk:app-launch-context, Class
gdk:button-event, GdkEvent
gdk:cairo-context, Class
gdk:cicp-params, Class
gdk:clipboard, Class
gdk:color-state, GBoxed
gdk:content-deserializer, Class
gdk:content-formats, GBoxed
gdk:content-provider, Class
gdk:content-serializer, Class
gdk:crossing-event, GdkEvent
gdk:cursor, Class
gdk:delete-event, GdkEvent
gdk:device, Class
gdk:device-pad, Interface
gdk:device-tool, Class
gdk:display, Class
gdk:display-manager, Class
gdk:dmabuf-formats, GBoxed
gdk:dmabuf-texture, Class
gdk:dmabuf-texture-builder, Class
gdk:dnd-event, GdkEvent
gdk:drag, Class
gdk:drag-surface, Interface
gdk:draw-context, Class
gdk:drop, Class
gdk:event, GdkEvent
gdk:event-sequence, GBoxed
gdk:focus-event, GdkEvent
gdk:frame-clock, Class
gdk:frame-timings, GBoxed
gdk:gl-context, Class
gdk:grab-broken-event, GdkEvent
gdk:key-event, GdkEvent
gdk:memory-texture, Class
gdk:monitor, Class
gdk:motion-event, GdkEvent
gdk:pad-event, GdkEvent
gdk:paintable, Interface
gdk:popup, Interface
gdk:popup-layout, GBoxed
gdk:proximity-event, GdkEvent
gdk:rectangle, GBoxed
gdk:rgba, GBoxed
gdk:scroll-event, GdkEvent
gdk:seat, Class
gdk:snapshot, Class
gdk:surface, Class
gdk:texture, Class
gdk:texture-downloader, GBoxed
gdk:toplevel, Interface
gdk:toplevel-layout, GBoxed
gdk:touch-event, GdkEvent
gdk:touchpad-event, GdkEvent
gdk:app-launch-context-display, Accessor
gdk:app-launch-context-set-desktop, Function
gdk:app-launch-context-set-icon, Function
gdk:app-launch-context-set-icon-name, Function
gdk:app-launch-context-set-timestamp, Function
gdk:button-event-button, Function
gdk:cairo-context-cairo-create, Function
gdk:cairo-draw-from-gl, Function
gdk:cairo-rectangle, Function
gdk:cairo-region, Function
gdk:cairo-region-create-from-surface, Function
gdk:cairo-set-source-pixbuf, Function
gdk:cairo-set-source-rgba, Function
gdk:cicp-params-build-color-state, Function
gdk:cicp-params-color-primaries, Accessor
gdk:cicp-params-matrix-coefficients, Accessor
gdk:cicp-params-new, Function
gdk:cicp-params-range, Accessor
gdk:cicp-params-transfer-function, Accessor
gdk:clipboard-content, Accessor
gdk:clipboard-display, Accessor
gdk:clipboard-formats, Accessor
gdk:clipboard-is-local, Function
gdk:clipboard-local, Accessor
gdk:clipboard-read-text-async, Function
gdk:clipboard-read-text-finish, Function
gdk:clipboard-read-texture-async, Function
gdk:clipboard-read-texture-finish, Function
gdk:clipboard-read-value-async, Function
gdk:clipboard-read-value-finish, Function
gdk:clipboard-set, Function
gdk:clipboard-set-content, Function
gdk:clipboard-set-text, Function
gdk:clipboard-set-texture, Function
gdk:clipboard-set-value, Function
gdk:clipboard-store-async, Function
gdk:clipboard-store-finish, Function
gdk:color-state-create-cicp-params, Function
gdk:color-state-equal, Function
gdk:color-state-rec2100-linear, Function
gdk:color-state-rec2100-pq, Function
gdk:color-state-srgb, Function
gdk:color-state-srgb-linear, Function
gdk:content-formats-contain-gtype, Function
gdk:content-formats-contain-mime-type, Function
gdk:content-formats-gtypes, Function
gdk:content-formats-match, Function
gdk:content-formats-match-gtype, Function
gdk:content-formats-match-mime-type, Function
gdk:content-formats-mime-types, Function
gdk:content-formats-new, Function
gdk:content-formats-new-for-gtype, Function
gdk:content-formats-parse, Function
gdk:content-formats-to-string, Function
gdk:content-formats-union, Function
gdk:content-formats-union-deserialize-gtypes, Function
gdk:content-formats-union-deserialize-mime-types, Function
gdk:content-formats-union-serialize-gtypes, Function
gdk:content-formats-union-serialize-mime-types, Function
gdk:content-provider-formats, Accessor
gdk:content-provider-new-for-value, Function
gdk:content-provider-storable-formats, Accessor
gdk:crossing-event-detail, Function
gdk:crossing-event-focus, Function
gdk:crossing-event-mode, Function
gdk:cursor-fallback, Accessor
gdk:cursor-hotspot-x, Accessor
gdk:cursor-hotspot-y, Accessor
gdk:cursor-name, Accessor
gdk:cursor-new-from-name, Function
gdk:cursor-new-from-texture, Function
gdk:cursor-texture, Accessor
gdk:device-caps-lock-state, Accessor
gdk:device-direction, Accessor
gdk:device-display, Accessor
gdk:device-has-bidi-layouts, Accessor
gdk:device-has-cursor, Accessor
gdk:device-modifier-state, Accessor
gdk:device-n-axes, Accessor
gdk:device-name, Accessor
gdk:device-num-lock-state, Accessor
gdk:device-num-touches, Accessor
gdk:device-pad-feature-group, Function
gdk:device-pad-group-n-modes, Function
gdk:device-pad-n-features, Function
gdk:device-pad-n-groups, Function
gdk:device-product-id, Accessor
gdk:device-scroll-lock-state, Accessor
gdk:device-seat, Accessor
gdk:device-source, Accessor
gdk:device-surface-at-position, Function
gdk:device-timestamp, Function
gdk:device-tool, Accessor
gdk:device-tool-axes, Accessor
gdk:device-tool-hardware-id, Accessor
gdk:device-tool-serial, Accessor
gdk:device-tool-tool-type, Accessor
gdk:device-vendor-id, Accessor
gdk:display-app-launch-context, Function
gdk:display-beep, Function
gdk:display-clipboard, Function
gdk:display-close, Function
gdk:display-composited, Accessor
gdk:display-create-gl-context, Function
gdk:display-default, Function
gdk:display-default-seat, Function
gdk:display-device-is-grabbed, Function
gdk:display-dmabuf-formats, Accessor
gdk:display-flush, Function
gdk:display-input-shapes, Accessor
gdk:display-is-closed, Function
gdk:display-is-composited, Function
gdk:display-is-rgba, Function
gdk:display-list-seats, Function
gdk:display-manager-default-display, Accessor
gdk:display-manager-get, Function
gdk:display-manager-list-displays, Function
gdk:display-manager-open-display, Function
gdk:display-map-keycode, Function
gdk:display-map-keyval, Function
gdk:display-monitor-at-surface, Function
gdk:display-monitors, Function
gdk:display-name, Function
gdk:display-notify-startup-complete, Function
gdk:display-open, Function
gdk:display-prepare-gl, Function
gdk:display-primary-clipboard, Function
gdk:display-rgba, Accessor
gdk:display-setting, Function
gdk:display-shadow-width, Accessor
gdk:display-startup-notification-id, Function
gdk:display-supports-input-shapes, Function
gdk:display-sync, Function
gdk:display-translate-key, Function
gdk:dmabuf-formats-contains, Function
gdk:dmabuf-formats-equal, Function
gdk:dmabuf-formats-format, Function
gdk:dmabuf-formats-n-formats, Function
gdk:dmabuf-texture-builder-display, Accessor
gdk:dmabuf-texture-builder-fourcc, Accessor
gdk:dmabuf-texture-builder-height, Accessor
gdk:dmabuf-texture-builder-modifier, Accessor
gdk:dmabuf-texture-builder-n-planes, Accessor
gdk:dmabuf-texture-builder-new, Function
gdk:dmabuf-texture-builder-premultiplied, Accessor
gdk:dmabuf-texture-builder-update-region, Accessor
gdk:dmabuf-texture-builder-update-texture, Accessor
gdk:dmabuf-texture-builder-width, Accessor
gdk:dnd-event-drop, Function
gdk:drag-action-is-unique, Function
gdk:drag-actions, Accessor
gdk:drag-begin, Function
gdk:drag-content, Accessor
gdk:drag-device, Accessor
gdk:drag-display, Accessor
gdk:drag-drag-surface, Function
gdk:drag-drop-done, Function
gdk:drag-formats, Accessor
gdk:drag-selected-action, Accessor
gdk:drag-set-hotspot, Function
gdk:drag-surface, Accessor
gdk:drag-surface-present, Function
gdk:drag-surface-size-set-size, Function
gdk:draw-context-begin-frame, Function
gdk:draw-context-display, Accessor
gdk:draw-context-end-frame, Function
gdk:draw-context-frame-region, Function
gdk:draw-context-is-in-frame, Function
gdk:draw-context-surface, Accessor
gdk:drop-actions, Accessor
gdk:drop-device, Accessor
gdk:drop-display, Accessor
gdk:drop-drag, Accessor
gdk:drop-finish, Function
gdk:drop-formats, Accessor
gdk:drop-read-value-async, Function
gdk:drop-read-value-finish, Function
gdk:drop-status, Function
gdk:drop-surface, Accessor
gdk:event-axes, Function
gdk:event-axis, Function
gdk:event-device, Function
gdk:event-device-tool, Function
gdk:event-display, Function
gdk:event-event-sequence, Function
gdk:event-event-type, Function
gdk:event-modifier-state, Function
gdk:event-pointer-emulated, Function
gdk:event-position, Function
gdk:event-seat, Function
gdk:event-surface, Function
gdk:event-time, Function
gdk:event-triggers-context-menu, Function
gdk:events-angle, Function
gdk:events-center, Function
gdk:events-distance, Function
gdk:focus-event-in, Function
gdk:frame-clock-begin-updating, Function
gdk:frame-clock-current-timings, Function
gdk:frame-clock-end-updating, Function
gdk:frame-clock-fps, Function
gdk:frame-clock-frame-counter, Function
gdk:frame-clock-frame-time, Function
gdk:frame-clock-history-start, Function
gdk:frame-clock-refresh-info, Function
gdk:frame-clock-request-phase, Function
gdk:frame-clock-timings, Function
gdk:frame-timings-complete, Function
gdk:frame-timings-frame-counter, Function
gdk:frame-timings-frame-time, Function
gdk:frame-timings-predicted-presentation-time, Function
gdk:frame-timings-presentation-time, Function
gdk:frame-timings-refresh-interval, Function
gdk:gl-context-allowed-apis, Accessor
gdk:gl-context-api, Accessor
gdk:gl-context-clear-current, Function
gdk:gl-context-current, Function
gdk:gl-context-debug-enabled, Function
gdk:gl-context-display, Function
gdk:gl-context-forward-compatible, Function
gdk:gl-context-is-legacy, Function
gdk:gl-context-make-current, Function
gdk:gl-context-realize, Function
gdk:gl-context-shared-context, Accessor
gdk:gl-context-surface, Function
gdk:gl-context-use-es, Function
gdk:gl-context-version, Function
gdk:grab-broken-event-grab-surface, Function
gdk:grab-broken-event-implicit, Function
gdk:key-event-consumed-modifiers, Function
gdk:key-event-is-modifier, Function
gdk:key-event-keycode, Function
gdk:key-event-keyval, Function
gdk:key-event-layout, Function
gdk:key-event-level, Function
gdk:key-event-match, Function
gdk:key-event-matches, Function
gdk:keyval-convert-case, Function
gdk:keyval-from-name, Function
gdk:keyval-is-lower, Function
gdk:keyval-is-upper, Function
gdk:keyval-name, Function
gdk:keyval-to-lower, Function
gdk:keyval-to-unicode, Function
gdk:keyval-to-upper, Function
gdk:memory-texture-new, Function
gdk:monitor-connector, Accessor
gdk:monitor-description, Accessor
gdk:monitor-display, Accessor
gdk:monitor-geometry, Accessor
gdk:monitor-height-mm, Accessor
gdk:monitor-is-valid, Function
gdk:monitor-manufacturer, Accessor
gdk:monitor-model, Accessor
gdk:monitor-refresh-rate, Accessor
gdk:monitor-scale, Accessor
gdk:monitor-scale-factor, Accessor
gdk:monitor-subpixel-layout, Accessor
gdk:monitor-valid, Accessor
gdk:monitor-width-mm, Accessor
gdk:pad-event-axis-value, Function
gdk:pad-event-button, Function
gdk:pad-event-group-mode, Function
gdk:paintable-compute-concrete-size, Function
gdk:paintable-current-image, Function
gdk:paintable-flags, Function
gdk:paintable-get-current-image-impl, Method
gdk:paintable-get-flags-impl, Method
gdk:paintable-get-intrinsic-aspect-ratio-impl, Method
gdk:paintable-get-intrinsic-height-impl, Method
gdk:paintable-get-intrinsic-width-impl, Method
gdk:paintable-intrinsic-aspect-ratio, Function
gdk:paintable-intrinsic-height, Function
gdk:paintable-intrinsic-width, Function
gdk:paintable-invalidate-contents, Function
gdk:paintable-invalidate-size, Function
gdk:paintable-new-empty, Function
gdk:paintable-snapshot, Function
gdk:paintable-snapshot-impl, Method
gdk:pango-layout-clip-region, Function
gdk:pango-layout-line-clip-region, Function
gdk:pixbuf-from-surface, Function
gdk:pixbuf-from-texture, Function
gdk:popup-autohide, Accessor
gdk:popup-layout-anchor-hints, Function
gdk:popup-layout-anchor-rect, Function
gdk:popup-layout-copy, Function
gdk:popup-layout-equal, Function
gdk:popup-layout-new, Function
gdk:popup-layout-offset, Function
gdk:popup-layout-rect-anchor, Function
gdk:popup-layout-shadow-width, Function
gdk:popup-layout-surface-anchor, Function
gdk:popup-parent, Accessor
gdk:popup-position-x, Function
gdk:popup-position-y, Function
gdk:popup-present, Function
gdk:popup-rect-anchor, Function
gdk:popup-surface-anchor, Function
gdk:rectangle-contains-point, Function
gdk:rectangle-copy, Function
gdk:rectangle-equal, Function
gdk:rectangle-height, Accessor
gdk:rectangle-intersect, Function
gdk:rectangle-new, Function
gdk:rectangle-union, Function
gdk:rectangle-width, Accessor
gdk:rectangle-x, Accessor
gdk:rectangle-y, Accessor
gdk:rgba-alpha, Accessor
gdk:rgba-blue, Accessor
gdk:rgba-copy, Function
gdk:rgba-equal, Function
gdk:rgba-green, Accessor
gdk:rgba-hash, Function
gdk:rgba-is-clear, Function
gdk:rgba-is-opaque, Function
gdk:rgba-new, Function
gdk:rgba-parse, Function
gdk:rgba-red, Accessor
gdk:rgba-to-string, Function
gdk:scroll-event-deltas, Function
gdk:scroll-event-direction, Function
gdk:scroll-event-is-stop, Function
gdk:scroll-event-unit, Function
gdk:seat-capabilities, Function
gdk:seat-devices, Function
gdk:seat-display, Accessor
gdk:seat-keyboard, Function
gdk:seat-pointer, Function
gdk:seat-tools, Function
gdk:set-allowed-backends, Function
gdk:surface-beep, Function
gdk:surface-create-cairo-context, Function
gdk:surface-create-gl-context, Function
gdk:surface-create-similar-surface, Function
gdk:surface-cursor, Accessor
gdk:surface-destroy, Function
gdk:surface-device-cursor, Function
gdk:surface-device-position, Function
gdk:surface-display, Accessor
gdk:surface-frame-clock, Accessor
gdk:surface-height, Accessor
gdk:surface-hide, Function
gdk:surface-is-destroyed, Function
gdk:surface-mapped, Accessor
gdk:surface-new-popup, Function
gdk:surface-new-toplevel, Function
gdk:surface-queue-render, Function
gdk:surface-request-layout, Function
gdk:surface-scale, Accessor
gdk:surface-scale-factor, Accessor
gdk:surface-set-input-region, Function
gdk:surface-set-opaque-region, Function
gdk:surface-translate-coordinates, Function
gdk:surface-width, Accessor
gdk:texture-color-state, Accessor
gdk:texture-download, Function
gdk:texture-downloader-color-state, Function
gdk:texture-downloader-copy, Function
gdk:texture-downloader-download-bytes, Function
gdk:texture-downloader-download-into, Function
gdk:texture-downloader-format, Function
gdk:texture-downloader-new, Function
gdk:texture-downloader-texture, Function
gdk:texture-format, Function
gdk:texture-height, Accessor
gdk:texture-new-for-pixbuf, Function
gdk:texture-new-from-bytes, Function
gdk:texture-new-from-file, Function
gdk:texture-new-from-filename, Function
gdk:texture-new-from-resource, Function
gdk:texture-save-to-png, Function
gdk:texture-save-to-png-bytes, Function
gdk:texture-save-to-tiff, Function
gdk:texture-save-to-tiff-bytes, Function
gdk:texture-width, Accessor
gdk:toplevel-begin-move, Function
gdk:toplevel-begin-resize, Function
gdk:toplevel-decorated, Accessor
gdk:toplevel-deletable, Accessor
gdk:toplevel-focus, Function
gdk:toplevel-fullscreen-mode, Accessor
gdk:toplevel-icon-list, Accessor
gdk:toplevel-inhibit-system-shortcuts, Function
gdk:toplevel-layout-copy, Function
gdk:toplevel-layout-equal, Function
gdk:toplevel-layout-fullscreen, Function
gdk:toplevel-layout-fullscreen-monitor, Function
gdk:toplevel-layout-maximized, Function
gdk:toplevel-layout-new, Function
gdk:toplevel-layout-resizable, Function
gdk:toplevel-lower, Function
gdk:toplevel-minimize, Function
gdk:toplevel-modal, Accessor
gdk:toplevel-present, Function
gdk:toplevel-restore-system-shortcuts, Function
gdk:toplevel-shortcuts-inhibited, Accessor
gdk:toplevel-show-window-menu, Function
gdk:toplevel-size-bounds, Function
gdk:toplevel-size-set-min-size, Function
gdk:toplevel-size-set-shadow-width, Function
gdk:toplevel-size-set-size, Function
gdk:toplevel-startup-id, Accessor
gdk:toplevel-state, Accessor
gdk:toplevel-supports-edge-constraints, Function
gdk:toplevel-title, Accessor
gdk:toplevel-titlebar-gesture, Function
gdk:toplevel-transient-for, Accessor
gdk:touch-event-emulating-pointer, Function
gdk:touchpad-event-deltas, Function
gdk:touchpad-event-gesture-phase, Function
gdk:touchpad-event-n-fingers, Function
gdk:touchpad-event-pinch-angle-delta, Function
gdk:touchpad-event-pinch-scale, Function
gdk:unicode-to-keyval, Function
gdk:anchor-hints, GFlags
gdk:axis-flags, GFlags
gdk:axis-use, GEnum
gdk:cicp-range, GEnum
gdk:crossing-mode, GEnum
gdk:device-pad-feature, GEnum
gdk:device-tool-type, GEnum
gdk:drag-action, GFlags
gdk:drag-cancel-reason, GEnum
gdk:drag-surface-size, CStruct
gdk:event-type, GEnum
gdk:frame-clock-phase, GFlags
gdk:fullscreen-mode, GEnum
gdk:gl-api, GFlags
gdk:gravity, GEnum
gdk:input-source, GEnum
gdk:key-match, GEnum
gdk:memory-format, GEnum
gdk:modifier-type, GFlags
gdk:notify-type, GEnum
gdk:paintable-flags, GFlags
gdk:scroll-direction, GEnum
gdk:scroll-unit, GEnum
gdk:seat-capabilities, GFlags
gdk:subpixel-layout, GEnum
gdk:surface-edge, GEnum
gdk:titlebar-gesture, GEnum
gdk:toplevel-size, CStruct
gdk:toplevel-state, GFlags
gdk:touchpad-gesture-phase, GEnum
gdk:+button-middle+, Constant
gdk:+button-primary+, Constant
gdk:+button-secondary+, Constant
gdk:+current-time+, Constant
gdk:+event-propagate+, Constant
gdk:+event-stop+, Constant
gdk:+memory-default+, Constant
gdk:+modifier-mask+, Constant
gio:action, Interface
gio:action-group, Interface
gio:action-map, Interface
gio:app-info, Interface
gio:app-launch-context, Class
gio:application, Class
gio:application-command-line, Class
gio:async-result, Interface
gio:cancellable, Class
gio:emblem, Class
gio:emblemed-icon, Class
gio:file, Interface
gio:file-icon, Class
gio:file-info, Class
gio:icon, Interface
gio:list-model, Interface
gio:list-store, Class
gio:loadable-icon, Interface
gio:menu, Class
gio:menu-attribute-iter, Class
gio:menu-item, Class
gio:menu-link-iter, Class
gio:menu-model, Class
gio:notification, Class
gio:permission, Class
gio:property-action, Class
gio:resource, GBoxed
gio:settings, Class
gio:simple-action, Class
gio:simple-action-group, Class
gio:simple-permission, Class
gio:task, Class
gio:themed-icon, Class
gio:action-activate, Function
gio:action-change-state, Function
gio:action-enabled, Accessor
gio:action-group-action-added, Function
gio:action-group-action-enabled, Function
gio:action-group-action-enabled-changed, Function
gio:action-group-action-parameter-type, Function
gio:action-group-action-removed, Function
gio:action-group-action-state, Function
gio:action-group-action-state-changed, Function
gio:action-group-action-state-hint, Function
gio:action-group-action-state-type, Function
gio:action-group-activate-action, Function
gio:action-group-change-action-state, Function
gio:action-group-has-action, Function
gio:action-group-list-actions, Function
gio:action-map-add-action, Function
gio:action-map-add-action-entries, Function
gio:action-map-lookup-action, Function
gio:action-map-remove-action, Function
gio:action-name, Accessor
gio:action-name-is-valid, Function
gio:action-parameter-type, Accessor
gio:action-parse-detailed-name, Function
gio:action-print-detailed-name, Function
gio:action-state, Accessor
gio:action-state-hint, Function
gio:action-state-type, Accessor
gio:app-info-add-supports-type, Function
gio:app-info-all, Function
gio:app-info-all-for-type, Function
gio:app-info-can-delete, Function
gio:app-info-can-remove-supports-type, Function
gio:app-info-commandline, Function
gio:app-info-create-from-commandline, Function
gio:app-info-default-for-type, Function
gio:app-info-default-for-uri-scheme, Function
gio:app-info-delete, Function
gio:app-info-description, Function
gio:app-info-display-name, Function
gio:app-info-dup, Function
gio:app-info-equal, Function
gio:app-info-executable, Function
gio:app-info-fallback-for-type, Function
gio:app-info-icon, Function
gio:app-info-id, Function
gio:app-info-launch, Function
gio:app-info-launch-default-for-uri, Function
gio:app-info-launch-default-for-uri-async, Function
gio:app-info-launch-default-for-uri-finish, Function
gio:app-info-launch-uris, Function
gio:app-info-name, Function
gio:app-info-recommended-for-type, Function
gio:app-info-remove-supports-type, Function
gio:app-info-reset-type-associations, Function
gio:app-info-set-as-default-for-extension, Function
gio:app-info-set-as-default-for-type, Function
gio:app-info-set-as-last-used-for-type, Function
gio:app-info-should-show, Function
gio:app-info-supported-types, Function
gio:app-info-supports-files, Function
gio:app-info-supports-uris, Function
gio:app-launch-context-display, Function
gio:app-launch-context-environment, Function
gio:app-launch-context-launch-failed, Function
gio:app-launch-context-new, Function
gio:app-launch-context-setenv, Function
gio:app-launch-context-startup-notify-id, Function
gio:app-launch-context-unsetenv, Function
gio:application-action-group, Accessor
gio:application-activate, Function
gio:application-add-main-option, Function
gio:application-add-main-option-entries, Function
gio:application-add-option-group, Function
gio:application-application-id, Accessor
gio:application-bind-busy-property, Function
gio:application-command-line-arguments, Function
gio:application-command-line-create-file-for-arg, Function
gio:application-command-line-cwd, Function
gio:application-command-line-environ, Function
gio:application-command-line-exit-status, Function
gio:application-command-line-getenv, Function
gio:application-command-line-is-remote, Accessor
gio:application-command-line-options-dict, Function
gio:application-command-line-platform-data, Function
gio:application-default, Function
gio:application-flags, Accessor
gio:application-hold, Function
gio:application-id-is-valid, Function
gio:application-inactivity-timeout, Accessor
gio:application-is-busy, Accessor
gio:application-is-registered, Accessor
gio:application-is-remote, Accessor
gio:application-mark-busy, Function
gio:application-new, Function
gio:application-open, Function
gio:application-quit, Function
gio:application-register, Function
gio:application-release, Function
gio:application-resource-base-path, Accessor
gio:application-run, Function
gio:application-send-notification, Function
gio:application-set-option-context-description, Function
gio:application-set-option-context-parameter-string, Function
gio:application-set-option-context-summary, Function
gio:application-unbind-busy-property, Function
gio:application-unmark-busy, Function
gio:application-version, Accessor
gio:application-withdraw-notification, Function
gio:async-result-is-tagged, Function
gio:async-result-source-object, Function
gio:async-result-user-data, Function
gio:cancellable-cancel, Function
gio:cancellable-current, Function
gio:cancellable-is-cancelled, Function
gio:cancellable-new, Function
gio:cancellable-pop-current, Function
gio:cancellable-push-current, Function
gio:cancellable-reset, Function
gio:cancellable-source-new, Function
gio:content-type-can-be-executable, Function
gio:content-type-description, Function
gio:content-type-equals, Function
gio:content-type-from-mime-type, Function
gio:content-type-generic-icon-name, Function
gio:content-type-icon, Function
gio:content-type-is-a, Function
gio:content-type-is-mime-type, Function
gio:content-type-is-unknown, Function
gio:content-type-mime-dirs, Function
gio:content-type-mime-type, Function
gio:content-type-symbolic-icon, Function
gio:content-types-registered, Function
gio:emblem-icon, Accessor
gio:emblem-new, Function
gio:emblem-new-with-origin, Function
gio:emblem-origin, Accessor
gio:emblemed-icon-add-emblem, Function
gio:emblemed-icon-clear-emblems, Function
gio:emblemed-icon-emblems, Function
gio:emblemed-icon-gicon, Accessor
gio:emblemed-icon-icon, Function
gio:emblemed-icon-new, Function
gio:file-basename, Function
gio:file-get-parse-name, Function
gio:file-icon-file, Accessor
gio:file-icon-new, Function
gio:file-info-access-date-time, Function  (undocumented)
gio:file-info-attribute-as-string, Function  (undocumented)
gio:file-info-attribute-boolean, Function  (undocumented)
gio:file-info-clear-status, Function  (undocumented)
gio:file-info-has-attribute, Function  (undocumented)
gio:file-info-has-namespace, Function  (undocumented)
gio:file-info-list-attributes, Function  (undocumented)
gio:file-info-modification-date-time, Function  (undocumented)
gio:file-info-name, Function  (undocumented)
gio:file-info-new, Function
gio:file-info-size, Function  (undocumented)
gio:file-new-for-commandline-arg, Function
gio:file-new-for-commandline-arg-and-cwd, Function
gio:file-new-for-path, Function
gio:file-new-for-uri, Function
gio:file-parse-name, Function
gio:file-path, Function
gio:file-query-info, Function
gio:file-uri, Function
gio:icon-deserialize, Function
gio:icon-equal, Function
gio:icon-hash, Function
gio:icon-new-for-string, Function
gio:icon-serialize, Function
gio:icon-to-string, Function
gio:list-model-get-item-impl, Generic
gio:list-model-get-item-type-impl, Generic
gio:list-model-get-n-items-impl, Generic
gio:list-model-item, Function
gio:list-model-item-type, Function
gio:list-model-items-changed, Function
gio:list-model-n-items, Function
gio:list-store-append, Function
gio:list-store-find, Function
gio:list-store-find-with-equal-func, Function
gio:list-store-insert, Function
gio:list-store-insert-sorted, Function
gio:list-store-item-type, Accessor
gio:list-store-n-items, Accessor
gio:list-store-new, Function
gio:list-store-remove, Function
gio:list-store-remove-all, Function
gio:list-store-sort, Function
gio:list-store-splice, Function
gio:menu-append, Function
gio:menu-append-item, Function
gio:menu-append-section, Function
gio:menu-append-submenu, Function
gio:menu-attribute-iter-name, Function
gio:menu-attribute-iter-next, Function
gio:menu-attribute-iter-value, Function
gio:menu-freeze, Function
gio:menu-insert, Function
gio:menu-insert-item, Function
gio:menu-insert-section, Function
gio:menu-insert-submenu, Function
gio:menu-item-attribute-value, Function
gio:menu-item-link, Function
gio:menu-item-new, Function
gio:menu-item-new-from-model, Function
gio:menu-item-new-section, Function
gio:menu-item-new-submenu, Function
gio:menu-item-set-action-and-target-value, Function
gio:menu-item-set-detailed-action, Function
gio:menu-item-set-icon, Function
gio:menu-item-set-label, Function
gio:menu-item-set-section, Function
gio:menu-item-set-submenu, Function
gio:menu-link-iter-name, Function
gio:menu-link-iter-next, Function
gio:menu-link-iter-value, Function
gio:menu-model-is-mutable, Function
gio:menu-model-item-attribute-value, Function
gio:menu-model-item-link, Function
gio:menu-model-items-changed, Function
gio:menu-model-iterate-item-attributes, Function
gio:menu-model-iterate-item-links, Function
gio:menu-model-n-items, Function
gio:menu-new, Function
gio:menu-prepend, Function
gio:menu-prepend-item, Function
gio:menu-prepend-section, Function
gio:menu-prepend-submenu, Function
gio:menu-remove, Function
gio:menu-remove-all, Function
gio:notification-add-button, Function
gio:notification-new, Function
gio:notification-set-body, Function
gio:notification-set-default-action, Function
gio:notification-set-icon, Function
gio:notification-set-priority, Function
gio:notification-set-title, Function
gio:permission-acquire, Function
gio:permission-allowed, Accessor
gio:permission-can-acquire, Accessor
gio:permission-can-release, Accessor
gio:permission-release, Function
gio:property-action-enabled, Accessor
gio:property-action-invert-boolean, Accessor
gio:property-action-name, Accessor
gio:property-action-new, Function
gio:property-action-object, Accessor
gio:property-action-parameter-type, Accessor
gio:property-action-property-name, Accessor
gio:property-action-state, Accessor
gio:property-action-state-type, Accessor
gio:resource-enumerate-children, Function
gio:resource-info, Function
gio:resource-load, Function
gio:resource-lookup-data, Function
gio:resources-enumerate-children, Function
gio:resources-info, Function
gio:resources-lookup-data, Function
gio:resources-register, Function
gio:resources-unregister, Function
gio:settings-backend, Generic Function  (undocumented)
gio:settings-delay-apply, Generic Function  (undocumented)
gio:settings-has-unapplied, Generic Function  (undocumented)
gio:settings-list-schemas, Function  (undocumented)
gio:settings-new, Function  (undocumented)
gio:settings-new-with-path, Function  (undocumented)
gio:settings-path, Generic Function  (undocumented)
gio:settings-schema, Generic Function  (undocumented)
gio:settings-schema-id, Generic Function  (undocumented)
gio:settings-settings-schema, Generic Function  (undocumented)
gio:simple-action-enabled, Accessor
gio:simple-action-group-add-entries, Function
gio:simple-action-group-insert, Function
gio:simple-action-group-lookup, Function
gio:simple-action-group-new, Function
gio:simple-action-group-remove, Function
gio:simple-action-name, Accessor
gio:simple-action-new, Function
gio:simple-action-new-stateful, Function
gio:simple-action-parameter-type, Accessor
gio:simple-action-set-state-hint, Function
gio:simple-action-state, Accessor
gio:simple-action-state-type, Accessor
gio:simple-permission-new, Function
gio:task-cancellable, Function
gio:task-check-cancellable, Function
gio:task-completed, Accessor
gio:task-context, Function
gio:task-new, Function
gio:task-priority, Function
gio:task-propagate-pointer, Function  (undocumented)
gio:task-return-boolean, Function
gio:task-return-pointer, Function  (undocumented)
gio:task-run-in-thread, Function  (undocumented)
gio:task-source-object, Function
gio:task-task-data, Function  (undocumented)
gio:themed-icon-append-name, Function
gio:themed-icon-name, Accessor
gio:themed-icon-names, Accessor
gio:themed-icon-new, Function
gio:themed-icon-new-from-names, Function
gio:themed-icon-new-with-default-fallbacks, Function
gio:themed-icon-prepend-name, Function
gio:themed-icon-use-default-fallbacks, Accessor
gio:with-resource, Macro
gio:with-resources, Macro
gio:app-info-create-flags, GFlags
gio:application-flags, GFlags
gio:async-ready-callback, Callback
gio:cancellable-source-func, Callback
gio:compare-data-func, Callback
gio:emblem-origin, GEnum
gio:equal-func-full, Callback
gio:file-query-info-flags, GFlags
gio:list-model-vtable, VTable
gio:notification-priority, GEnum
gio:resource-flags, GFlags
gio:resource-lookup-flags, GFlags
gio:task-thread-func, Symbol  (undocumented)
gio:file-as-namestring, Type
glib:boxed-cstruct-info, Struct  (undocumented)
glib:boxed-opaque-info, Struct  (undocumented)
glib:boxed-variant-info, Struct  (undocumented)
glib:bytes, GBoxed
glib:error, GBoxed
glib:gtype, Struct  (undocumented)
glib:variant-dict, GBoxed
glib:variant-type, GBoxed
glib:application-name, Function
glib:boxed-copy-fn, Generic Function  (undocumented)
glib:boxed-opaque-pointer, Generic Function  (undocumented)
glib:bytes-data, Function
glib:bytes-new, Function
glib:bytes-size, Function
glib:check-version, Function
glib:cl-cffi-glib-build-info, Function
glib:cleanup-translated-object-for-callback, Generic Function  (undocumented)
glib:free, Function
glib:gtype, Function
glib:gtype-id, Function
glib:gtype-name, Function
glib:idle-add, Function
glib:idle-source-new, Function
glib:key-file-boolean, Function
glib:key-file-boolean-list, Function
glib:key-file-comment, Function
glib:key-file-double, Function
glib:key-file-double-list, Function
glib:key-file-free, Function
glib:key-file-groups, Function
glib:key-file-has-group, Function
glib:key-file-has-key, Function
glib:key-file-int64, Function
glib:key-file-integer, Function
glib:key-file-integer-list, Function
glib:key-file-keys, Function
glib:key-file-load-from-bytes, Function
glib:key-file-load-from-data, Function
glib:key-file-load-from-data-dirs, Function
glib:key-file-load-from-dirs, Function
glib:key-file-load-from-file, Function
glib:key-file-locale-for-key, Function
glib:key-file-locale-string, Function
glib:key-file-locale-string-list, Function
glib:key-file-new, Function
glib:key-file-ref, Function
glib:key-file-remove-comment, Function
glib:key-file-remove-group, Function
glib:key-file-remove-key, Function
glib:key-file-save-to-file, Function
glib:key-file-set-list-separator, Function
glib:key-file-start-group, Function
glib:key-file-string, Function
glib:key-file-string-list, Function
glib:key-file-to-data, Function
glib:key-file-uint64, Function
glib:key-file-unref, Function
glib:key-file-value, Function
glib:main-context-default, Function
glib:main-context-find-source-by-id, Function
glib:main-context-is-owner, Function
glib:main-context-iteration, Function
glib:main-context-new, Function
glib:main-context-pending, Function
glib:main-context-ref, Function
glib:main-context-unref, Function
glib:main-loop-context, Function
glib:main-loop-is-running, Function
glib:main-loop-new, Function
glib:main-loop-quit, Function
glib:main-loop-ref, Function
glib:main-loop-run, Function
glib:main-loop-unref, Function
glib:make-boxed-type, Generic Function  (undocumented)
glib:malloc, Function
glib:option-context-add-group, Function
glib:option-context-add-main-entries, Function
glib:option-context-description, Function
glib:option-context-free, Function
glib:option-context-help, Function
glib:option-context-help-enabled, Function
glib:option-context-ignore-unknown-options, Function
glib:option-context-main-group, Function
glib:option-context-new, Function
glib:option-context-parse, Function
glib:option-context-parse-strv, Function
glib:option-context-set-translate-func, Function
glib:option-context-set-translation-domain, Function
glib:option-context-strict-posix, Function
glib:option-context-summary, Function
glib:option-group-add-entries, Function
glib:option-group-new, Function
glib:option-group-ref, Function
glib:option-group-set-translate-func, Function
glib:option-group-set-translation-domain, Function
glib:option-group-unref, Function
glib:pointer, Generic Function  (undocumented)
glib:prgname, Function
glib:source-add-child-source, Function
glib:source-attach, Function
glib:source-can-recurse, Function
glib:source-context, Function
glib:source-destroy, Function
glib:source-id, Function
glib:source-is-destroyed, Function
glib:source-name, Function
glib:source-priority, Function
glib:source-ready-time, Function
glib:source-remove, Function
glib:source-remove-child-source, Function
glib:source-set-callback, Function
glib:source-set-name-by-id, Function
glib:source-time, Function
glib:symbol-for-gtype, Function
glib:timeout-add, Function
glib:timeout-add-seconds, Function
glib:timeout-source-new, Function
glib:timeout-source-new-seconds, Function
glib:variant-boolean, Function
glib:variant-byte, Function
glib:variant-classify, Function
glib:variant-compare, Function
glib:variant-dict-contains, Function
glib:variant-dict-end, Function
glib:variant-dict-insert-value, Function
glib:variant-dict-lookup-value, Function
glib:variant-dict-new, Function
glib:variant-dict-remove, Function
glib:variant-double, Function
glib:variant-equal, Function
glib:variant-handle, Function
glib:variant-int16, Function
glib:variant-int32, Function
glib:variant-int64, Function
glib:variant-is-container, Function
glib:variant-is-floating, Function
glib:variant-is-object-path, Function
glib:variant-is-of-type, Function
glib:variant-is-signature, Function
glib:variant-new-boolean, Function
glib:variant-new-byte, Function
glib:variant-new-double, Function
glib:variant-new-handle, Function
glib:variant-new-int16, Function
glib:variant-new-int32, Function
glib:variant-new-int64, Function
glib:variant-new-object-path, Function
glib:variant-new-signature, Function
glib:variant-new-string, Function
glib:variant-new-tuple, Function
glib:variant-new-uint16, Function
glib:variant-new-uint32, Function
glib:variant-new-uint64, Function
glib:variant-new-variant, Function
glib:variant-parse, Function
glib:variant-print, Function
glib:variant-ref, Function
glib:variant-ref-sink, Function
glib:variant-string, Function
glib:variant-take-ref, Function
glib:variant-type, Function
glib:variant-type-copy, Function
glib:variant-type-dup-string, Function
glib:variant-type-element, Function
glib:variant-type-equal, Function
glib:variant-type-first, Function
glib:variant-type-hash, Function
glib:variant-type-is-array, Function
glib:variant-type-is-basic, Function
glib:variant-type-is-container, Function
glib:variant-type-is-definite, Function
glib:variant-type-is-dict-entry, Function
glib:variant-type-is-maybe, Function
glib:variant-type-is-subtype-of, Function
glib:variant-type-is-tuple, Function
glib:variant-type-is-variant, Function
glib:variant-type-key, Function
glib:variant-type-n-items, Function
glib:variant-type-new, Function
glib:variant-type-new-array, Function
glib:variant-type-new-dict-entry, Function
glib:variant-type-new-maybe, Function
glib:variant-type-new-tuple, Function
glib:variant-type-next, Function
glib:variant-type-string, Function
glib:variant-type-string-is-valid, Function
glib:variant-type-value, Function
glib:variant-uint16, Function
glib:variant-uint32, Function
glib:variant-uint64, Function
glib:variant-unref, Function
glib:with-key-file, Macro
glib:with-key-file-from-data, Macro
glib:with-key-file-from-file, Macro
glib:with-option-context, Macro
glib:with-option-group, Macro
glib:+major-version+, Constant
glib:+micro-version+, Constant
glib:+minor-version+, Constant
glib:gtype, Struct
glib:key-file-flags, Bitfield
glib:option-arg, CEnum
glib:option-flags, Bitfield
glib:source-func, Callback
glib:translate-func, Callback
glib:variant, CStruct
glib:variant-class, CEnum
glib:date-time, Type
glib:key-file, CStruct
glib:list-t, Type
glib:main-context, CStruct
glib:main-loop, CStruct
glib:option-context, CStruct
glib:option-group, CStruct
glib:quark-as-string, Type
glib:slist-t, Type
glib:source, CStruct
glib:strv-t, Type
glib:unichar, Type
glib:+priority-default+, Constant
glib:+priority-default-idle+, Constant
glib:+priority-high+, Constant
glib:+priority-high-idle+, Constant
glib:+priority-low+, Constant
glib:+source-continue+, Constant
glib:+source-remove+, Constant
gobject:binding, Class
gobject:initially-unowned, Class
gobject:object, Class
gobject:signal-query, Struct
gobject:type-t, Type
gobject:binding-dup-source, Function
gobject:binding-dup-target, Function
gobject:binding-flags, Accessor
gobject:binding-source, Accessor
gobject:binding-source-property, Accessor
gobject:binding-target, Accessor
gobject:binding-target-property, Accessor
gobject:binding-unbind, Function
gobject:define-gobject-subclass, Macro  (undocumented)
gobject:get-gvalue-for-type, Generic Function  (undocumented)
gobject:is-object, Function
gobject:is-param-spec, Function
gobject:object-bind-property, Function
gobject:object-bind-property-full, Function
gobject:object-class-find-property, Function
gobject:object-class-init, Generic Function  (undocumented)
gobject:object-class-list-properties, Function
gobject:object-data, Function
gobject:object-freeze-notify, Function
gobject:object-has-reference, Accessor
gobject:object-instance-init, Generic Function  (undocumented)
gobject:object-interface-find-property, Function
gobject:object-interface-list-properties, Function
gobject:object-new, Function
gobject:object-notify, Function
gobject:object-pointer, Accessor
gobject:object-property, Function
gobject:object-ref, Function
gobject:object-ref-count, Function
gobject:object-set-data-full, Function
gobject:object-thaw-notify, Function
gobject:object-unref, Function
gobject:param-spec-blurb, Function
gobject:param-spec-boolean, Function
gobject:param-spec-boxed, Function
gobject:param-spec-char, Function
gobject:param-spec-default-value, Function
gobject:param-spec-double, Function
gobject:param-spec-enum, Function
gobject:param-spec-flags, Function
gobject:param-spec-float, Function
gobject:param-spec-gtype, Function
gobject:param-spec-int, Function
gobject:param-spec-int64, Function
gobject:param-spec-internal, Function
gobject:param-spec-long, Function
gobject:param-spec-name, Function
gobject:param-spec-nick, Function
gobject:param-spec-object, Function
gobject:param-spec-param, Function
gobject:param-spec-pointer, Function
gobject:param-spec-ref, Function
gobject:param-spec-ref-sink, Function
gobject:param-spec-string, Function
gobject:param-spec-type, Function
gobject:param-spec-type-name, Function
gobject:param-spec-uchar, Function
gobject:param-spec-uint, Function
gobject:param-spec-uint64, Function
gobject:param-spec-ulong, Function
gobject:param-spec-unref, Function
gobject:param-spec-value-type, Function
gobject:param-value-defaults, Function
gobject:param-value-set-default, Function
gobject:param-value-validate, Function
gobject:set-gvalue-for-type, Generic Function  (undocumented)
gobject:signal-connect, Function
gobject:signal-emit, Function
gobject:signal-handler-block, Function
gobject:signal-handler-disconnect, Function
gobject:signal-handler-find, Function
gobject:signal-handler-is-connected, Function
gobject:signal-handler-unblock, Function
gobject:signal-has-handler-pending, Function
gobject:signal-list-ids, Function
gobject:signal-lookup, Function
gobject:signal-name, Function
gobject:signal-query, Function
gobject:signal-query-owner-type, Accessor
gobject:signal-query-param-types, Accessor
gobject:signal-query-return-type, Accessor
gobject:signal-query-signal-detail, Accessor
gobject:signal-query-signal-flags, Accessor
gobject:signal-query-signal-id, Accessor
gobject:signal-query-signal-name, Accessor
gobject:signal-stop-emission, Function
gobject:strdup-value-contents, Function
gobject:type-check-class-type, Function
gobject:type-check-instance-type, Function
gobject:type-children, Function
gobject:type-class-peek, Function
gobject:type-class-peek-parent, Function
gobject:type-class-ref, Function
gobject:type-class-unref, Function
gobject:type-default-interface-peek, Function
gobject:type-default-interface-ref, Function
gobject:type-default-interface-unref, Function
gobject:type-depth, Function
gobject:type-ensure, Function
gobject:type-from-class, Function
gobject:type-from-instance, Function
gobject:type-from-interface, Function
gobject:type-fundamental, Function
gobject:type-instance-class, Function
gobject:type-interface-peek, Function
gobject:type-interface-prerequisites, Function
gobject:type-interfaces, Function
gobject:type-is-a, Function
gobject:type-is-abstract, Function
gobject:type-is-boxed, Function
gobject:type-is-classed, Function
gobject:type-is-derived, Function
gobject:type-is-enum, Function
gobject:type-is-flags, Function
gobject:type-is-fundamental, Function
gobject:type-is-interface, Function
gobject:type-is-object, Function
gobject:type-is-param, Function
gobject:type-is-value, Function
gobject:type-is-value-type, Function
gobject:type-name, Function
gobject:type-next-base, Function
gobject:type-parent, Function
gobject:type-qdata, Function
gobject:value-boolean, Function
gobject:value-boxed, Function
gobject:value-char, Function
gobject:value-copy, Function
gobject:value-double, Function
gobject:value-enum, Function
gobject:value-flags, Function
gobject:value-float, Function
gobject:value-get, Function
gobject:value-gtype, Function
gobject:value-holds, Function
gobject:value-init, Function
gobject:value-int, Function
gobject:value-int64, Function
gobject:value-long, Function
gobject:value-object, Function
gobject:value-param, Function
gobject:value-pointer, Function
gobject:value-reset, Function
gobject:value-schar, Function
gobject:value-set, Function
gobject:value-string, Function
gobject:value-take-boxed, Function
gobject:value-type, Function
gobject:value-type-compatible, Function
gobject:value-type-name, Function
gobject:value-uchar, Function
gobject:value-uint, Function
gobject:value-uint64, Function
gobject:value-ulong, Function
gobject:value-unset, Function
gobject:value-variant, Function
gobject:with-value, Macro
gobject:with-values, Macro
gobject:binding-flags, GFlags
gobject:binding-transform-func, Callback
gobject:connect-flags, Bitfield
gobject:destroy-notify, Callback
gobject:enum, Symbol  (undocumented)
gobject:enum-class, CStruct
gobject:enum-value, CStruct
gobject:flags, Symbol  (undocumented)
gobject:flags-class, CStruct
gobject:flags-value, CStruct
gobject:param, Symbol  (undocumented)
gobject:param-flags, Bitfield
gobject:param-spec, CStruct
gobject:param-spec-boolean, CStruct
gobject:param-spec-boxed, CStruct
gobject:param-spec-char, CStruct
gobject:param-spec-double, CStruct
gobject:param-spec-enum, CStruct
gobject:param-spec-flags, CStruct
gobject:param-spec-float, CStruct
gobject:param-spec-gtype, CStruct
gobject:param-spec-int, CStruct
gobject:param-spec-int64, CStruct
gobject:param-spec-long, CStruct
gobject:param-spec-object, CStruct
gobject:param-spec-param, CStruct
gobject:param-spec-pointer, CStruct
gobject:param-spec-string, CStruct
gobject:param-spec-uchar, CStruct
gobject:param-spec-uint, CStruct
gobject:param-spec-uint64, CStruct
gobject:param-spec-ulong, CStruct
gobject:signal-flags, Bitfield
gobject:type-class, CStruct
gobject:type-instance, CStruct
gobject:type-interface, CStruct
gobject:value, CStruct
graphene:box-alloc, Function
graphene:box-bounding-sphere, Function
graphene:box-center, Function
graphene:box-contains-box, Function
graphene:box-contains-point, Function
graphene:box-depth, Function
graphene:box-empty, Function
graphene:box-equal, Function
graphene:box-expand, Function
graphene:box-expand-scalar, Function
graphene:box-expand-vec3, Function
graphene:box-free, Function
graphene:box-height, Function
graphene:box-infinite, Function
graphene:box-init, Function
graphene:box-init-from-box, Function
graphene:box-init-from-vec3, Function
graphene:box-intersection, Function
graphene:box-max, Function
graphene:box-min, Function
graphene:box-minus-one, Function
graphene:box-one, Function
graphene:box-one-minus-one, Function
graphene:box-size, Function
graphene:box-union, Function
graphene:box-vertices, Function
graphene:box-width, Function
graphene:box-zero, Function
graphene:euler-alloc, Function
graphene:euler-alpha, Function
graphene:euler-beta, Function
graphene:euler-equal, Function
graphene:euler-free, Function
graphene:euler-gamma, Function
graphene:euler-init, Function
graphene:euler-init-from-euler, Function
graphene:euler-init-from-matrix, Function
graphene:euler-init-from-quaternion, Function
graphene:euler-init-from-radians, Function
graphene:euler-init-from-vec3, Function
graphene:euler-order, Function
graphene:euler-reorder, Function
graphene:euler-to-matrix, Function
graphene:euler-to-quaternion, Function
graphene:euler-to-vec3, Function
graphene:euler-x, Function
graphene:euler-y, Function
graphene:euler-z, Function
graphene:frustum-alloc, Function
graphene:frustum-contains-point, Function
graphene:frustum-equal, Function
graphene:frustum-free, Function
graphene:frustum-init, Function
graphene:frustum-init-from-frustum, Function
graphene:frustum-init-from-matrix, Function
graphene:frustum-intersects-box, Function
graphene:frustum-intersects-sphere, Function
graphene:frustum-planes, Function
graphene:matrix-alloc, Function
graphene:matrix-decompose, Function
graphene:matrix-determinant, Function
graphene:matrix-equal, Function
graphene:matrix-equal-fast, Function
graphene:matrix-free, Function
graphene:matrix-init-from-2d, Function
graphene:matrix-init-from-float, Function
graphene:matrix-init-from-matrix, Function
graphene:matrix-init-from-vec4, Function
graphene:matrix-init-frustum, Function
graphene:matrix-init-identity, Function
graphene:matrix-init-look-at, Function
graphene:matrix-init-ortho, Function
graphene:matrix-init-perspective, Function
graphene:matrix-init-rotate, Function
graphene:matrix-init-scale, Function
graphene:matrix-init-skew, Function
graphene:matrix-init-translate, Function
graphene:matrix-interpolate, Function
graphene:matrix-inverse, Function
graphene:matrix-is-2d, Function
graphene:matrix-is-backface-visible, Function
graphene:matrix-is-identity, Function
graphene:matrix-is-singular, Function
graphene:matrix-multiply, Function
graphene:matrix-near, Function
graphene:matrix-normalize, Function
graphene:matrix-perspective, Function
graphene:matrix-project-point, Function
graphene:matrix-project-rect, Function
graphene:matrix-project-rect-bounds, Function
graphene:matrix-rotate, Function
graphene:matrix-rotate-euler, Function
graphene:matrix-rotate-quaternion, Function
graphene:matrix-rotate-x, Function
graphene:matrix-rotate-y, Function
graphene:matrix-rotate-z, Function
graphene:matrix-row, Function
graphene:matrix-scale, Function
graphene:matrix-skew-xy, Function
graphene:matrix-skew-xz, Function
graphene:matrix-skew-yz, Function
graphene:matrix-to-2d, Function
graphene:matrix-to-float, Function
graphene:matrix-transform-bounds, Function
graphene:matrix-transform-box, Function
graphene:matrix-transform-point, Function
graphene:matrix-transform-point3d, Function
graphene:matrix-transform-ray, Function
graphene:matrix-transform-rect, Function
graphene:matrix-transform-sphere, Function
graphene:matrix-transform-vec3, Function
graphene:matrix-transform-vec4, Function
graphene:matrix-translate, Function
graphene:matrix-transpose, Function
graphene:matrix-unproject-point3d, Function
graphene:matrix-untransform-bounds, Function
graphene:matrix-untransform-point, Function
graphene:matrix-value, Function
graphene:matrix-x-scale, Function
graphene:matrix-x-translation, Function
graphene:matrix-y-scale, Function
graphene:matrix-y-translation, Function
graphene:matrix-z-scale, Function
graphene:matrix-z-translation, Function
graphene:plane-alloc, Function
graphene:plane-constant, Function
graphene:plane-distance, Function
graphene:plane-equal, Function
graphene:plane-free, Function
graphene:plane-init, Function
graphene:plane-init-from-plane, Function
graphene:plane-init-from-point, Function
graphene:plane-init-from-points, Function
graphene:plane-init-from-vec4, Function
graphene:plane-negate, Function
graphene:plane-normal, Function
graphene:plane-normalize, Function
graphene:plane-transform, Function
graphene:point-alloc, Function
graphene:point-distance, Function
graphene:point-equal, Function
graphene:point-free, Function
graphene:point-init, Function
graphene:point-init-from-point, Function
graphene:point-init-from-vec2, Function
graphene:point-interpolate, Function
graphene:point-near, Function
graphene:point-to-vec2, Function
graphene:point-x, Accessor
graphene:point-y, Accessor
graphene:point-zero, Function
graphene:point3d-alloc, Function
graphene:point3d-cross, Function
graphene:point3d-distance, Function
graphene:point3d-dot, Function
graphene:point3d-equal, Function
graphene:point3d-free, Function
graphene:point3d-init, Function
graphene:point3d-init-from-point, Function
graphene:point3d-init-from-vec3, Function
graphene:point3d-interpolate, Function
graphene:point3d-length, Function
graphene:point3d-near, Function
graphene:point3d-normalize, Function
graphene:point3d-normalize-viewport, Function
graphene:point3d-scale, Function
graphene:point3d-to-vec3, Function
graphene:point3d-x, Accessor
graphene:point3d-y, Accessor
graphene:point3d-z, Accessor
graphene:point3d-zero, Function
graphene:quad-alloc, Function
graphene:quad-bounds, Function
graphene:quad-contains, Function
graphene:quad-free, Function
graphene:quad-init, Function
graphene:quad-init-from-points, Function
graphene:quad-init-from-rect, Function
graphene:quad-point, Function
graphene:quaternion-add, Function
graphene:quaternion-alloc, Function
graphene:quaternion-dot, Function
graphene:quaternion-equal, Function
graphene:quaternion-free, Function
graphene:quaternion-init, Function
graphene:quaternion-init-from-angle-vec3, Function
graphene:quaternion-init-from-angles, Function
graphene:quaternion-init-from-euler, Function
graphene:quaternion-init-from-matrix, Function
graphene:quaternion-init-from-quaternion, Function
graphene:quaternion-init-from-radians, Function
graphene:quaternion-init-from-vec4, Function
graphene:quaternion-init-identity, Function
graphene:quaternion-invert, Function
graphene:quaternion-multiply, Function
graphene:quaternion-normalize, Function
graphene:quaternion-scale, Function
graphene:quaternion-slerp, Function
graphene:quaternion-to-angle-vec3, Function
graphene:quaternion-to-angles, Function
graphene:quaternion-to-matrix, Function
graphene:quaternion-to-radians, Function
graphene:quaternion-to-vec4, Function
graphene:ray-alloc, Function
graphene:ray-closest-point-to-point, Function
graphene:ray-direction, Function
graphene:ray-distance-to-plane, Function
graphene:ray-distance-to-point, Function
graphene:ray-equal, Function
graphene:ray-free, Function
graphene:ray-init, Function
graphene:ray-init-from-ray, Function
graphene:ray-init-from-vec3, Function
graphene:ray-intersect-box, Function
graphene:ray-intersect-sphere, Function
graphene:ray-intersect-triangle, Function
graphene:ray-intersects-box, Function
graphene:ray-intersects-sphere, Function
graphene:ray-intersects-triangle, Function
graphene:ray-origin, Function
graphene:ray-position-at, Function
graphene:rect-alloc, Function
graphene:rect-area, Function
graphene:rect-bottom-left, Function
graphene:rect-bottom-right, Function
graphene:rect-center, Function
graphene:rect-contains-point, Function
graphene:rect-contains-rect, Function
graphene:rect-equal, Function
graphene:rect-expand, Function
graphene:rect-free, Function
graphene:rect-height, Function
graphene:rect-init, Function
graphene:rect-init-from-rect, Function
graphene:rect-inset, Function
graphene:rect-interpolate, Function
graphene:rect-intersection, Function
graphene:rect-normalize, Function
graphene:rect-offset, Function
graphene:rect-origin, Accessor
graphene:rect-round-extents, Function
graphene:rect-scale, Function
graphene:rect-size, Accessor
graphene:rect-top-left, Function
graphene:rect-top-right, Function
graphene:rect-union, Function
graphene:rect-vertices, Function
graphene:rect-width, Function
graphene:rect-x, Function
graphene:rect-y, Function
graphene:rect-zero, Function
graphene:size-alloc, Function
graphene:size-equal, Function
graphene:size-free, Function
graphene:size-height, Accessor
graphene:size-init, Function
graphene:size-init-from-size, Function
graphene:size-interpolate, Function
graphene:size-scale, Function
graphene:size-width, Accessor
graphene:size-zero, Function
graphene:sphere-alloc, Function
graphene:sphere-bounding-box, Function
graphene:sphere-center, Function
graphene:sphere-contains-point, Function
graphene:sphere-distance, Function
graphene:sphere-equal, Function
graphene:sphere-free, Function
graphene:sphere-init, Function
graphene:sphere-init-from-points, Function
graphene:sphere-init-from-sphere, Function
graphene:sphere-init-from-vectors, Function
graphene:sphere-is-empty, Function
graphene:sphere-radius, Function
graphene:sphere-translate, Function
graphene:triangle-alloc, Function
graphene:triangle-area, Function
graphene:triangle-barycoords, Function
graphene:triangle-bounding-box, Function
graphene:triangle-contains-point, Function
graphene:triangle-equal, Function
graphene:triangle-free, Function
graphene:triangle-init-from-float, Function
graphene:triangle-init-from-point3d, Function
graphene:triangle-init-from-vec3, Function
graphene:triangle-midpoint, Function
graphene:triangle-normal, Function
graphene:triangle-plane, Function
graphene:triangle-points, Function
graphene:triangle-uv, Function
graphene:triangle-vertices, Function
graphene:vec2-add, Function
graphene:vec2-alloc, Function
graphene:vec2-divide, Function
graphene:vec2-dot, Function
graphene:vec2-equal, Function
graphene:vec2-free, Function
graphene:vec2-init, Function
graphene:vec2-init-from-float, Function
graphene:vec2-init-from-vec2, Function
graphene:vec2-interpolate, Function
graphene:vec2-length, Function
graphene:vec2-max, Function
graphene:vec2-min, Function
graphene:vec2-multiply, Function
graphene:vec2-near, Function
graphene:vec2-negate, Function
graphene:vec2-normalize, Function
graphene:vec2-one, Function
graphene:vec2-scale, Function
graphene:vec2-subtract, Function
graphene:vec2-to-float, Function
graphene:vec2-x, Function
graphene:vec2-x-axis, Function
graphene:vec2-y, Function
graphene:vec2-y-axis, Function
graphene:vec2-zero, Function
graphene:vec3-add, Function
graphene:vec3-alloc, Function
graphene:vec3-cross, Function
graphene:vec3-divide, Function
graphene:vec3-dot, Function
graphene:vec3-equal, Function
graphene:vec3-free, Function
graphene:vec3-init, Function
graphene:vec3-init-from-float, Function
graphene:vec3-init-from-vec3, Function
graphene:vec3-interpolate, Function
graphene:vec3-length, Function
graphene:vec3-max, Function
graphene:vec3-min, Function
graphene:vec3-multiply, Function
graphene:vec3-near, Function
graphene:vec3-negate, Function
graphene:vec3-normalize, Function
graphene:vec3-one, Function
graphene:vec3-scale, Function
graphene:vec3-subtract, Function
graphene:vec3-to-float, Function
graphene:vec3-x, Function
graphene:vec3-x-axis, Function
graphene:vec3-xy, Function
graphene:vec3-xy0, Function
graphene:vec3-xyz0, Function
graphene:vec3-xyz1, Function
graphene:vec3-xyzw, Function
graphene:vec3-y, Function
graphene:vec3-y-axis, Function
graphene:vec3-z, Function
graphene:vec3-z-axis, Function
graphene:vec3-zero, Function
graphene:vec4-add, Function
graphene:vec4-alloc, Function
graphene:vec4-divide, Function
graphene:vec4-dot, Function
graphene:vec4-equal, Function
graphene:vec4-free, Function
graphene:vec4-init, Function
graphene:vec4-init-from-float, Function
graphene:vec4-init-from-vec2, Function
graphene:vec4-init-from-vec3, Function
graphene:vec4-init-from-vec4, Function
graphene:vec4-interpolate, Function
graphene:vec4-length, Function
graphene:vec4-max, Function
graphene:vec4-min, Function
graphene:vec4-multiply, Function
graphene:vec4-near, Function
graphene:vec4-negate, Function
graphene:vec4-normalize, Function
graphene:vec4-one, Function
graphene:vec4-scale, Function
graphene:vec4-subtract, Function
graphene:vec4-to-float, Function
graphene:vec4-w, Function
graphene:vec4-w-axis, Function
graphene:vec4-x, Function
graphene:vec4-x-axis, Function
graphene:vec4-xy, Function
graphene:vec4-xyz, Function
graphene:vec4-y, Function
graphene:vec4-y-axis, Function
graphene:vec4-z, Function
graphene:vec4-z-axis, Function
graphene:vec4-zero, Function
graphene:with-box, Macro
graphene:with-boxes, Macro
graphene:with-euler, Macro
graphene:with-eulers, Macro
graphene:with-frustum, Macro
graphene:with-frustums, Macro
graphene:with-matrices, Macro
graphene:with-matrix, Macro
graphene:with-object, Macro
graphene:with-objects, Macro
graphene:with-plane, Macro
graphene:with-planes, Macro
graphene:with-point, Macro
graphene:with-point3d, Macro
graphene:with-point3ds, Macro
graphene:with-points, Macro
graphene:with-quad, Macro
graphene:with-quads, Macro
graphene:with-quaternion, Macro
graphene:with-quaternions, Macro
graphene:with-ray, Macro
graphene:with-rays, Macro
graphene:with-rect, Macro
graphene:with-rects, Macro
graphene:with-size, Macro
graphene:with-sizes, Macro
graphene:with-sphere, Macro
graphene:with-spheres, Macro
graphene:with-triangle, Macro
graphene:with-triangles, Macro
graphene:with-vec2, Macro
graphene:with-vec2s, Macro
graphene:with-vec3, Macro
graphene:with-vec3s, Macro
graphene:with-vec4, Macro
graphene:with-vec4s, Macro
graphene:box-t, CStruct
graphene:euler-order-t, CEnum
graphene:euler-t, CStruct
graphene:frustum-t, CStruct
graphene:matrix-t, CStruct
graphene:plane-t, CStruct
graphene:point-t, CStruct
graphene:point3d-t, CStruct
graphene:quad-t, CStruct
graphene:quaternion-t, CStruct
graphene:ray-intersection-kind-t, CEnum
graphene:ray-t, CStruct
graphene:rect-t, CStruct
graphene:size-t, CStruct
graphene:sphere-t, CStruct
graphene:triangle-t, CStruct
graphene:vec2-t, CStruct
graphene:vec3-t, CStruct
graphene:vec4-t, CStruct
graphene:+vec2-len+, Constant
graphene:+vec3-len+, Constant
graphene:+vec4-len+, Constant
gsk:blend-node, GskRenderNode
gsk:blur-node, GskRenderNode
gsk:border-node, GskRenderNode
gsk:cairo-node, GskRenderNode
gsk:cairo-renderer, Class
gsk:clip-node, GskRenderNode
gsk:color-matrix-node, GskRenderNode
gsk:color-node, GskRenderNode
gsk:conic-gradient-node, GskRenderNode
gsk:container-node, GskRenderNode
gsk:cross-fade-node, GskRenderNode
gsk:debug-node, GskRenderNode
gsk:fill-node, GskRenderNode
gsk:gl-renderer, Class
gsk:inset-shadow-node, GskRenderNode
gsk:linear-gradient-node, GskRenderNode
gsk:mask-node, GskRenderNode
gsk:ngl-renderer, Class
gsk:opacity-node, GskRenderNode
gsk:outset-shadow-node, GskRenderNode
gsk:path, GBoxed
gsk:path-builder, GBoxed
gsk:path-measure, GBoxed
gsk:path-point, GBoxed
gsk:radial-gradient-node, GskRenderNode
gsk:render-node, GskRenderNode
gsk:renderer, Class
gsk:repeat-node, GskRenderNode
gsk:repeating-linear-gradient-node, GskRenderNode
gsk:repeating-radial-gradient-node, GskRenderNode
gsk:rounded-clip-node, GskRenderNode
gsk:shadow-node, GskRenderNode
gsk:stroke, GBoxed
gsk:stroke-node, GskRenderNode
gsk:subsurface-node, GskRenderNode
gsk:text-node, GskRenderNode
gsk:texture-node, GskRenderNode
gsk:texture-scale-node, GskRenderNode
gsk:transform, GBoxed
gsk:transform-node, GskRenderNode
gsk:blend-node-blend-mode, Function
gsk:blend-node-bottom-child, Function
gsk:blend-node-new, Function
gsk:blend-node-top-child, Function
gsk:blur-node-child, Function
gsk:blur-node-new, Function
gsk:blur-node-radius, Function
gsk:border-node-colors, Function
gsk:border-node-new, Function
gsk:border-node-outline, Function
gsk:border-node-widths, Function
gsk:cairo-node-draw-context, Function
gsk:cairo-node-new, Function
gsk:cairo-node-surface, Function
gsk:cairo-renderer-new, Function
gsk:clip-node-child, Function
gsk:clip-node-clip, Function
gsk:clip-node-new, Function
gsk:color-matrix-node-child, Function
gsk:color-matrix-node-color-matrix, Function
gsk:color-matrix-node-color-offset, Function
gsk:color-matrix-node-new, Function
gsk:color-node-color, Function
gsk:color-node-new, Function
gsk:conic-gradient-node-center, Function
gsk:conic-gradient-node-color-stops, Function
gsk:conic-gradient-node-n-color-stops, Function
gsk:conic-gradient-node-new, Function
gsk:conic-gradient-node-rotation, Function
gsk:container-node-child, Function
gsk:container-node-n-children, Function
gsk:container-node-new, Function
gsk:cross-fade-node-end-child, Function
gsk:cross-fade-node-new, Function
gsk:cross-fade-node-progress, Function
gsk:cross-fade-node-start-child, Function
gsk:debug-node-child, Function
gsk:debug-node-message, Function
gsk:debug-node-new, Function
gsk:fill-node-child, Function
gsk:fill-node-fill-rule, Function
gsk:fill-node-new, Function
gsk:fill-node-path, Function
gsk:gl-renderer-new, Function
gsk:inset-shadow-node-blur-radius, Function
gsk:inset-shadow-node-color, Function
gsk:inset-shadow-node-dx, Function
gsk:inset-shadow-node-dy, Function
gsk:inset-shadow-node-new, Function
gsk:inset-shadow-node-outline, Function
gsk:inset-shadow-node-spread, Function
gsk:linear-gradient-node-color-stops, Function
gsk:linear-gradient-node-end, Function
gsk:linear-gradient-node-n-color-stops, Function
gsk:linear-gradient-node-new, Function
gsk:linear-gradient-node-start, Function
gsk:mask-node-mask, Function
gsk:mask-node-mask-mode, Function
gsk:mask-node-new, Function
gsk:mask-node-source, Function
gsk:ngl-renderer-new, Function
gsk:opacity-node-child, Function
gsk:opacity-node-new, Function
gsk:opacity-node-opacity, Function
gsk:outset-shadow-node-blur-radius, Function
gsk:outset-shadow-node-color, Function
gsk:outset-shadow-node-dx, Function
gsk:outset-shadow-node-dy, Function
gsk:outset-shadow-node-new, Function
gsk:outset-shadow-node-outline, Function
gsk:outset-shadow-node-spread, Function
gsk:path-bounds, Function
gsk:path-builder-add-cairo-path, Function
gsk:path-builder-add-circle, Function
gsk:path-builder-add-layout, Function
gsk:path-builder-add-path, Function
gsk:path-builder-add-rect, Function
gsk:path-builder-add-reverse-path, Function
gsk:path-builder-add-rounded-rect, Function
gsk:path-builder-add-segment, Function
gsk:path-builder-arc-to, Function
gsk:path-builder-close, Function
gsk:path-builder-conic-to, Function
gsk:path-builder-cubic-to, Function
gsk:path-builder-current-point, Function
gsk:path-builder-html-arc-to, Function
gsk:path-builder-line-to, Function
gsk:path-builder-move-to, Function
gsk:path-builder-new, Function
gsk:path-builder-quad-to, Function
gsk:path-builder-rel-arc-to, Function
gsk:path-builder-rel-conic-to, Function
gsk:path-builder-rel-cubic-to, Function
gsk:path-builder-rel-html-arc-to, Function
gsk:path-builder-rel-line-to, Function
gsk:path-builder-rel-move-to, Function
gsk:path-builder-rel-quad-to, Function
gsk:path-builder-rel-svg-arc-to, Function
gsk:path-builder-svg-arc-to, Function
gsk:path-builder-to-path, Function
gsk:path-closest-point, Function
gsk:path-end-point, Function
gsk:path-foreach, Function
gsk:path-in-fill, Function
gsk:path-is-closed, Function
gsk:path-is-empty, Function
gsk:path-measure-length, Function
gsk:path-measure-new, Function
gsk:path-measure-new-with-tolerance, Function
gsk:path-measure-path, Function
gsk:path-measure-point, Function
gsk:path-measure-tolerance, Function
gsk:path-parse, Function
gsk:path-point-compare, Function
gsk:path-point-copy, Function
gsk:path-point-curvature, Function
gsk:path-point-distance, Function
gsk:path-point-equal, Function
gsk:path-point-position, Function
gsk:path-point-rotation, Function
gsk:path-point-tangent, Function
gsk:path-start-point, Function
gsk:path-stroke-bounds, Function
gsk:path-to-cairo, Function
gsk:path-to-string, Function
gsk:radial-gradient-node-center, Function
gsk:radial-gradient-node-color-stops, Function
gsk:radial-gradient-node-end, Function
gsk:radial-gradient-node-hradius, Function
gsk:radial-gradient-node-n-color-stops, Function
gsk:radial-gradient-node-new, Function
gsk:radial-gradient-node-start, Function
gsk:radial-gradient-node-vradius, Function
gsk:render-node-bounds, Function
gsk:render-node-deserialize, Function
gsk:render-node-draw, Function
gsk:render-node-node-type, Function
gsk:render-node-ref, Function
gsk:render-node-serialize, Function
gsk:render-node-unref, Function
gsk:render-node-write-to-file, Function
gsk:renderer-is-realized, Function
gsk:renderer-new-for-surface, Function
gsk:renderer-realize, Function
gsk:renderer-realized, Accessor
gsk:renderer-render, Function
gsk:renderer-render-texture, Function
gsk:renderer-surface, Accessor
gsk:renderer-unrealize, Function
gsk:repeat-node-child, Function
gsk:repeat-node-child-bounds, Function
gsk:repeat-node-new, Function
gsk:repeating-linear-gradient-node-new, Function
gsk:repeating-radial-gradient-node-new, Function
gsk:rounded-clip-node-child, Function
gsk:rounded-clip-node-clip, Function
gsk:rounded-clip-node-new, Function
gsk:rounded-rect-bounds, Function
gsk:rounded-rect-contains-point, Function
gsk:rounded-rect-contains-rect, Function
gsk:rounded-rect-corner, Function
gsk:rounded-rect-init, Function
gsk:rounded-rect-init-copy, Function
gsk:rounded-rect-init-from-rect, Function
gsk:rounded-rect-intersects-rect, Function
gsk:rounded-rect-is-rectilinear, Function
gsk:rounded-rect-normalize, Function
gsk:rounded-rect-offset, Function
gsk:rounded-rect-shrink, Function
gsk:shadow-node-child, Function
gsk:shadow-node-n-shadows, Function
gsk:shadow-node-new, Function
gsk:shadow-node-shadow, Function
gsk:stroke-copy, Function
gsk:stroke-dash, Function
gsk:stroke-dash-offset, Function
gsk:stroke-equal, Function
gsk:stroke-line-cap, Function
gsk:stroke-line-join, Function
gsk:stroke-line-width, Function
gsk:stroke-miter-limit, Function
gsk:stroke-new, Function
gsk:stroke-node-child, Function
gsk:stroke-node-new, Function
gsk:stroke-node-path, Function
gsk:stroke-node-stroke, Function
gsk:stroke-to-cairo, Function
gsk:subsurface-node-child, Function
gsk:subsurface-node-new, Function
gsk:subsurface-node-subsurface, Function
gsk:text-node-color, Function
gsk:text-node-font, Function
gsk:text-node-has-color-glyphs, Function
gsk:text-node-new, Function
gsk:text-node-num-glyphs, Function
gsk:text-node-offset, Function
gsk:texture-node-new, Function
gsk:texture-node-texture, Function
gsk:texture-scale-new, Function
gsk:texture-scale-node-filter, Function
gsk:texture-scale-node-texture, Function
gsk:transform-category, Function
gsk:transform-equal, Function
gsk:transform-invert, Function
gsk:transform-matrix, Function
gsk:transform-new, Function
gsk:transform-node-child, Function
gsk:transform-node-new, Function
gsk:transform-node-transform, Function
gsk:transform-parse, Function
gsk:transform-perspective, Function
gsk:transform-rotate, Function
gsk:transform-rotate-3d, Function
gsk:transform-scale, Function
gsk:transform-scale-3d, Function
gsk:transform-skew, Function
gsk:transform-to-2d, Function
gsk:transform-to-2d-components, Function
gsk:transform-to-affine, Function
gsk:transform-to-matrix, Function
gsk:transform-to-string, Function
gsk:transform-to-translate, Function
gsk:transform-transform, Function
gsk:transform-transform-bounds, Function
gsk:transform-transform-point, Function
gsk:transform-translate, Function
gsk:transform-translate-3d, Function
gsk:blend-mode, GEnum
gsk:corner, GEnum
gsk:fill-rule, GEnum
gsk:line-cap, GEnum
gsk:line-join, GEnum
gsk:mask-mode, GEnum
gsk:path-direction, GEnum
gsk:path-foreach-flags, GFlags
gsk:path-foreach-func, Callback
gsk:path-operation, GEnum
gsk:render-node-type, GEnum
gsk:rounded-rect, CStruct
gsk:scaling-filter, GEnum
gsk:transform-category, GEnum
gtk:about-dialog, Class
gtk:accessible, Interface
gtk:accessible-list, GBoxed
gtk:accessible-range, Interface
gtk:accessible-text, Interface
gtk:action-bar, Class
gtk:actionable, Interface
gtk:activate-action, Class
gtk:adjustment, Class
gtk:alert-dialog, Class
gtk:alternative-trigger, Class
gtk:any-filter, Class
gtk:app-chooser, Interface
gtk:app-chooser-button, Class
gtk:app-chooser-dialog, Class
gtk:app-chooser-widget, Class
gtk:application, Class
gtk:application-window, Class
gtk:aspect-frame, Class
gtk:assistant, Class
gtk:assistant-page, Class
gtk:at-context, Class
gtk:bin-layout, Class
gtk:bitset, GBoxed
gtk:bookmark-list, Class
gtk:bool-filter, Class
gtk:border, GBoxed
gtk:box, Class
gtk:box-layout, Class
gtk:buildable, Interface
gtk:builder, Class
gtk:builder-cl-scope, Class
gtk:builder-list-item-factory, Class
gtk:builder-scope, Interface
gtk:button, Class
gtk:calendar, Class
gtk:callback-action, Class
gtk:cell-area, Class
gtk:cell-area-box, Class
gtk:cell-area-context, Class
gtk:cell-editable, Interface
gtk:cell-layout, Interface
gtk:cell-renderer, Class
gtk:cell-renderer-accel, Class
gtk:cell-renderer-combo, Class
gtk:cell-renderer-pixbuf, Class
gtk:cell-renderer-progress, Class
gtk:cell-renderer-spin, Class
gtk:cell-renderer-spinner, Class
gtk:cell-renderer-text, Class
gtk:cell-renderer-toggle, Class
gtk:cell-view, Class
gtk:center-box, Class
gtk:center-layout, Class
gtk:check-button, Class
gtk:color-button, Class
gtk:color-chooser, Interface
gtk:color-chooser-dialog, Class
gtk:color-chooser-widget, Class
gtk:color-dialog, Class
gtk:color-dialog-button, Class
gtk:column-view, Class
gtk:column-view-cell, Class
gtk:column-view-column, Class
gtk:column-view-row, Class
gtk:column-view-sorter, Class
gtk:combo-box, Class
gtk:combo-box-text, Class
gtk:constraint, Class
gtk:constraint-guide, Class
gtk:constraint-layout, Class
gtk:constraint-layout-child, Class
gtk:constraint-target, Interface
gtk:css-provider, Class
gtk:css-section, GBoxed
gtk:custom-filter, Class
gtk:custom-layout, Class
gtk:custom-sorter, Class
gtk:dialog, Class
gtk:directory-list, Class
gtk:drag-icon, Class
gtk:drag-source, Class
gtk:drawing-area, Class
gtk:drop-controller-motion, Class
gtk:drop-down, Class
gtk:drop-target, Class
gtk:drop-target-async, Class
gtk:editable, Interface
gtk:editable-label, Class
gtk:emoji-chooser, Class
gtk:entry, Class
gtk:entry-buffer, Class
gtk:entry-completion, Class
gtk:event-controller, Class
gtk:event-controller-focus, Class
gtk:event-controller-key, Class
gtk:event-controller-legacy, Class
gtk:event-controller-motion, Class
gtk:event-controller-scroll, Class
gtk:every-filter, Class
gtk:expander, Class
gtk:expression, GtkExpression
gtk:expression-watch, GBoxed
gtk:file-chooser, Interface
gtk:file-chooser-dialog, Class
gtk:file-chooser-native, Class
gtk:file-chooser-widget, Class
gtk:file-dialog, Class
gtk:file-filter, Class
gtk:file-launcher, Class
gtk:filter, Class
gtk:filter-list-model, Class
gtk:fixed, Class
gtk:fixed-layout, Class
gtk:fixed-layout-child, Class
gtk:flatten-list-model, Class
gtk:flow-box, Class
gtk:flow-box-child, Class
gtk:font-button, Class
gtk:font-chooser, Interface
gtk:font-chooser-dialog, Class
gtk:font-chooser-widget, Class
gtk:font-dialog, Class
gtk:font-dialog-button, Class
gtk:frame, Class
gtk:gesture, Class
gtk:gesture-click, Class
gtk:gesture-drag, Class
gtk:gesture-long-press, Class
gtk:gesture-pan, Class
gtk:gesture-rotate, Class
gtk:gesture-single, Class
gtk:gesture-stylus, Class
gtk:gesture-swipe, Class
gtk:gesture-zoom, Class
gtk:gl-area, Class
gtk:graphics-offload, Class
gtk:grid, Class
gtk:grid-layout, Class
gtk:grid-layout-child, Class
gtk:grid-view, Class
gtk:header-bar, Class
gtk:icon-paintable, Class
gtk:icon-theme, Class
gtk:icon-view, Class
gtk:im-context, Class
gtk:im-context-simple, Class
gtk:im-multicontext, Class
gtk:image, Class
gtk:info-bar, Class
gtk:inscription, Class
gtk:keyval-trigger, Class
gtk:label, Class
gtk:layout-child, Class
gtk:layout-manager, Class
gtk:level-bar, Class
gtk:link-button, Class
gtk:list-base, Class
gtk:list-box, Class
gtk:list-box-row, Class
gtk:list-header, Class
gtk:list-item, Class
gtk:list-item-factory, Class
gtk:list-list-model, Class  (undocumented)
gtk:list-store, Class
gtk:list-view, Class
gtk:lock-button, Class
gtk:map-list-model, Class
gtk:media-controls, Class
gtk:media-file, Class
gtk:media-stream, Class
gtk:menu-button, Class
gtk:message-dialog, Class
gtk:mnemonic-action, Class
gtk:mnemonic-trigger, Class
gtk:multi-filter, Class
gtk:multi-selection, Class
gtk:multi-sorter, Class
gtk:named-action, Class
gtk:native, Interface
gtk:native-dialog, Class
gtk:never-trigger, Class
gtk:no-selection, Class
gtk:notebook, Class
gtk:notebook-page, Class
gtk:notebook-pages, Class
gtk:nothing-action, Class
gtk:numeric-sorter, Class
gtk:orientable, Interface
gtk:overlay, Class
gtk:overlay-layout, Class
gtk:overlay-layout-child, Class
gtk:pad-controller, Class
gtk:page-setup, Class
gtk:page-setup-unix-dialog, Class
gtk:paned, Class
gtk:paper-size, GBoxed
gtk:password-entry, Class
gtk:password-entry-buffer, Class
gtk:picture, Class
gtk:popover, Class
gtk:popover-menu, Class
gtk:popover-menu-bar, Class
gtk:print-backend, Class
gtk:print-context, Class
gtk:print-dialog, Class
gtk:print-job, Class
gtk:print-operation, Class
gtk:print-operation-preview, Interface
gtk:print-settings, Class
gtk:print-setup, GBoxed
gtk:print-unix-dialog, Class
gtk:printer, Class
gtk:progress-bar, Class
gtk:range, Class
gtk:recent-info, GBoxed
gtk:recent-manager, Class
gtk:requisition, GBoxed
gtk:revealer, Class
gtk:root, Interface
gtk:scale, Class
gtk:scale-button, Class
gtk:scroll-info, GBoxed
gtk:scrollable, Interface
gtk:scrollbar, Class
gtk:scrolled-window, Class
gtk:search-bar, Class
gtk:search-entry, Class
gtk:section-model, Interface
gtk:selection-filter-model, Class
gtk:selection-model, Interface
gtk:separator, Class
gtk:settings, Class
gtk:shortcut, Class
gtk:shortcut-action, Class
gtk:shortcut-controller, Class
gtk:shortcut-label, Class
gtk:shortcut-manager, Interface
gtk:shortcut-trigger, Class
gtk:shortcuts-group, Class
gtk:shortcuts-section, Class
gtk:shortcuts-shortcut, Class
gtk:shortcuts-window, Class
gtk:signal-action, Class
gtk:signal-list-item-factory, Class
gtk:single-selection, Class
gtk:size-group, Class
gtk:slice-list-model, Class
gtk:snapshot, Class
gtk:sort-list-model, Class
gtk:sorter, Class
gtk:spin-button, Class
gtk:spinner, Class
gtk:stack, Class
gtk:stack-page, Class
gtk:stack-sidebar, Class
gtk:stack-switcher, Class
gtk:statusbar, Class
gtk:string-filter, Class
gtk:string-list, Class
gtk:string-object, Class
gtk:string-sorter, Class
gtk:style-context, Class
gtk:style-provider, Interface
gtk:switch, Class
gtk:symbolic-paintable, Interface
gtk:text, Class
gtk:text-buffer, Class
gtk:text-child-anchor, Class
gtk:text-iter, GBoxed
gtk:text-mark, Class
gtk:text-tag, Class
gtk:text-tag-table, Class
gtk:text-view, Class
gtk:toggle-button, Class
gtk:tooltip, Class
gtk:tree-drag-dest, Interface
gtk:tree-drag-source, Interface
gtk:tree-expander, Class
gtk:tree-iter, GBoxed
gtk:tree-list-model, Class
gtk:tree-list-row, Class
gtk:tree-list-row-sorter, Class
gtk:tree-model, Interface
gtk:tree-model-filter, Class
gtk:tree-model-sort, Class
gtk:tree-path, GBoxed
gtk:tree-row-reference, GBoxed
gtk:tree-selection, Class
gtk:tree-sortable, Interface
gtk:tree-store, Class
gtk:tree-view, Class
gtk:tree-view-column, Class
gtk:uri-launcher, Class
gtk:video, Class
gtk:viewport, Class
gtk:volume-button, Class
gtk:widget, Class
gtk:widget-paintable, Class
gtk:window, Class
gtk:window-controls, Class
gtk:window-group, Class
gtk:window-handle, Class
gtk:about-dialog-add-credit-section, Function
gtk:about-dialog-artists, Accessor
gtk:about-dialog-authors, Accessor
gtk:about-dialog-comments, Accessor
gtk:about-dialog-copyright, Accessor
gtk:about-dialog-documenters, Accessor
gtk:about-dialog-license, Accessor
gtk:about-dialog-license-type, Accessor
gtk:about-dialog-logo, Accessor
gtk:about-dialog-logo-icon-name, Accessor
gtk:about-dialog-new, Function
gtk:about-dialog-program-name, Accessor
gtk:about-dialog-system-information, Accessor
gtk:about-dialog-translator-credits, Accessor
gtk:about-dialog-version, Accessor
gtk:about-dialog-website, Accessor
gtk:about-dialog-website-label, Accessor
gtk:about-dialog-wrap-license, Accessor
gtk:accelerator-default-mod-mask, Function
gtk:accelerator-label, Function
gtk:accelerator-name, Function
gtk:accelerator-parse, Function
gtk:accelerator-valid, Function
gtk:accessible-accessible-parent, Function
gtk:accessible-accessible-role, Accessor
gtk:accessible-announce, Function
gtk:accessible-at-context, Function
gtk:accessible-bounds, Function
gtk:accessible-first-accessible-child, Function
gtk:accessible-list-new-from-list, Function
gtk:accessible-list-objects, Function
gtk:accessible-next-accessible-sibling, Function
gtk:accessible-platform-state, Function
gtk:accessible-property-init-value, Function
gtk:accessible-relation-init-value, Function
gtk:accessible-reset-property, Function
gtk:accessible-reset-relation, Function
gtk:accessible-reset-state, Function
gtk:accessible-state-init-value, Function
gtk:accessible-text-caret-position, Function
gtk:accessible-text-contents, Function
gtk:accessible-text-contents-at, Function
gtk:accessible-text-extents, Function
gtk:accessible-text-offset, Function
gtk:accessible-text-update-caret-position, Function
gtk:accessible-text-update-contents, Function
gtk:accessible-text-update-selection-bound, Function
gtk:accessible-update-next-accessible-sibling, Function
gtk:accessible-update-property, Function
gtk:accessible-update-relation, Function
gtk:accessible-update-state, Function
gtk:action-bar-center-widget, Function
gtk:action-bar-new, Function
gtk:action-bar-pack-end, Function
gtk:action-bar-pack-start, Function
gtk:action-bar-remove, Function
gtk:action-bar-revealed, Accessor
gtk:actionable-action-name, Accessor
gtk:actionable-action-target, Accessor
gtk:actionable-set-detailed-action-name, Function
gtk:activate-action-get, Function
gtk:adjustment-clamp-page, Function
gtk:adjustment-configure, Function
gtk:adjustment-lower, Accessor
gtk:adjustment-minimum-increment, Function
gtk:adjustment-new, Function
gtk:adjustment-page-increment, Accessor
gtk:adjustment-page-size, Accessor
gtk:adjustment-step-increment, Accessor
gtk:adjustment-upper, Accessor
gtk:adjustment-value, Accessor
gtk:alert-dialog-buttons, Accessor
gtk:alert-dialog-cancel-button, Accessor
gtk:alert-dialog-choose, Function
gtk:alert-dialog-choose-finish, Function
gtk:alert-dialog-default-button, Accessor
gtk:alert-dialog-detail, Accessor
gtk:alert-dialog-message, Accessor
gtk:alert-dialog-modal, Accessor
gtk:alert-dialog-new, Function
gtk:alert-dialog-show, Function
gtk:alternative-trigger-first, Accessor
gtk:alternative-trigger-new, Function
gtk:alternative-trigger-second, Accessor
gtk:any-filter-new, Function
gtk:app-chooser-app-info, Function
gtk:app-chooser-button-append-custom-item, Function
gtk:app-chooser-button-append-separator, Function
gtk:app-chooser-button-heading, Accessor
gtk:app-chooser-button-modal, Accessor
gtk:app-chooser-button-new, Function
gtk:app-chooser-button-set-active-custom-item, Function
gtk:app-chooser-button-show-default-item, Accessor
gtk:app-chooser-button-show-dialog-item, Accessor
gtk:app-chooser-content-type, Accessor
gtk:app-chooser-dialog-gfile, Accessor
gtk:app-chooser-dialog-heading, Accessor
gtk:app-chooser-dialog-new, Function
gtk:app-chooser-dialog-new-for-content-type, Function
gtk:app-chooser-dialog-widget, Function
gtk:app-chooser-refresh, Function
gtk:app-chooser-widget-default-text, Accessor
gtk:app-chooser-widget-new, Function
gtk:app-chooser-widget-show-all, Accessor
gtk:app-chooser-widget-show-default, Accessor
gtk:app-chooser-widget-show-fallback, Accessor
gtk:app-chooser-widget-show-other, Accessor
gtk:app-chooser-widget-show-recommended, Accessor
gtk:application-accels-for-action, Function
gtk:application-actions-for-accel, Function
gtk:application-active-window, Accessor
gtk:application-add-window, Function
gtk:application-inhibit, Function
gtk:application-list-action-descriptions, Function
gtk:application-menu-by-id, Function
gtk:application-menubar, Accessor
gtk:application-new, Function
gtk:application-register-session, Accessor
gtk:application-remove-window, Function
gtk:application-screensaver-active, Accessor
gtk:application-uninhibit, Function
gtk:application-window-by-id, Function
gtk:application-window-help-overlay, Function
gtk:application-window-id, Function
gtk:application-window-new, Function
gtk:application-window-show-menubar, Accessor
gtk:application-windows, Function
gtk:aspect-frame-child, Accessor
gtk:aspect-frame-new, Function
gtk:aspect-frame-obey-child, Accessor
gtk:aspect-frame-ratio, Accessor
gtk:aspect-frame-xalign, Accessor
gtk:aspect-frame-yalign, Accessor
gtk:assistant-add-action-widget, Function
gtk:assistant-append-page, Function
gtk:assistant-commit, Function
gtk:assistant-current-page, Function
gtk:assistant-insert-page, Function
gtk:assistant-n-pages, Function
gtk:assistant-new, Function
gtk:assistant-next-page, Function
gtk:assistant-nth-page, Function
gtk:assistant-page, Function
gtk:assistant-page-child, Accessor
gtk:assistant-page-complete, Function
gtk:assistant-page-title, Function
gtk:assistant-page-type, Function
gtk:assistant-pages, Accessor
gtk:assistant-prepend-page, Function
gtk:assistant-previous-page, Function
gtk:assistant-remove-action-widget, Function
gtk:assistant-remove-page, Function
gtk:assistant-set-forward-page-func, Function
gtk:assistant-update-buttons-state, Function
gtk:assistant-use-header-bar, Accessor
gtk:at-context-accessible, Accessor
gtk:at-context-accessible-role, Accessor
gtk:at-context-create, Function
gtk:at-context-display, Accessor
gtk:bin-layout-new, Function
gtk:bitset-add, Function
gtk:bitset-add-range, Function
gtk:bitset-add-range-closed, Function
gtk:bitset-add-rectangle, Function
gtk:bitset-contains, Function
gtk:bitset-copy, Function
gtk:bitset-difference, Function
gtk:bitset-equals, Function
gtk:bitset-intersect, Function
gtk:bitset-is-empty, Function
gtk:bitset-iter-init-at, Function
gtk:bitset-iter-init-first, Function
gtk:bitset-iter-init-last, Function
gtk:bitset-iter-is-valid, Function
gtk:bitset-iter-next, Function
gtk:bitset-iter-previous, Function
gtk:bitset-iter-value, Function
gtk:bitset-maximum, Function
gtk:bitset-minimum, Function
gtk:bitset-new-empty, Function
gtk:bitset-new-range, Function
gtk:bitset-nth, Function
gtk:bitset-remove, Function
gtk:bitset-remove-all, Function
gtk:bitset-remove-range, Function
gtk:bitset-remove-range-closed, Function
gtk:bitset-remove-rectangle, Function
gtk:bitset-shift-left, Function
gtk:bitset-shift-right, Function
gtk:bitset-size, Function
gtk:bitset-size-in-range, Function
gtk:bitset-splice, Function
gtk:bitset-subtract, Function
gtk:bitset-union, Function
gtk:bookmark-list-attributes, Accessor
gtk:bookmark-list-filename, Accessor
gtk:bookmark-list-io-priority, Accessor
gtk:bookmark-list-is-loading, Function
gtk:bookmark-list-item-type, Accessor
gtk:bookmark-list-loading, Accessor
gtk:bookmark-list-n-items, Accessor
gtk:bookmark-list-new, Function
gtk:bool-filter-expression, Accessor
gtk:bool-filter-invert, Accessor
gtk:bool-filter-new, Function
gtk:border-bottom, Accessor
gtk:border-copy, Function
gtk:border-left, Accessor
gtk:border-new, Function
gtk:border-right, Accessor
gtk:border-top, Accessor
gtk:box-append, Function
gtk:box-baseline-child, Accessor
gtk:box-baseline-position, Accessor
gtk:box-homogeneous, Accessor
gtk:box-insert-child-after, Function
gtk:box-layout-baseline-child, Accessor
gtk:box-layout-baseline-position, Accessor
gtk:box-layout-homogeneous, Accessor
gtk:box-layout-new, Function
gtk:box-layout-spacing, Accessor
gtk:box-new, Function
gtk:box-prepend, Function
gtk:box-remove, Function
gtk:box-reorder-child-after, Function
gtk:box-spacing, Accessor
gtk:buildable-buildable-id, Function
gtk:builder-add-from-file, Function
gtk:builder-add-from-resource, Function
gtk:builder-add-from-string, Function
gtk:builder-add-objects-from-file, Function
gtk:builder-add-objects-from-resource, Function
gtk:builder-add-objects-from-string, Function
gtk:builder-current-object, Accessor
gtk:builder-expose-object, Function
gtk:builder-list-item-factory-bytes, Accessor
gtk:builder-list-item-factory-new-from-bytes, Function
gtk:builder-list-item-factory-new-from-resource, Function
gtk:builder-list-item-factory-resource, Accessor
gtk:builder-list-item-factory-scope, Accessor
gtk:builder-new, Function
gtk:builder-new-from-file, Function
gtk:builder-new-from-resource, Function
gtk:builder-new-from-string, Function
gtk:builder-object, Function
gtk:builder-objects, Function
gtk:builder-scope, Accessor
gtk:builder-translation-domain, Accessor
gtk:button-can-shrink, Accessor
gtk:button-child, Accessor
gtk:button-has-frame, Accessor
gtk:button-icon-name, Accessor
gtk:button-label, Accessor
gtk:button-new, Function
gtk:button-new-from-icon-name, Function
gtk:button-new-with-label, Function
gtk:button-new-with-mnemonic, Function
gtk:button-use-underline, Accessor
gtk:calendar-clear-marks, Function
gtk:calendar-date, Function
gtk:calendar-day, Accessor
gtk:calendar-day-is-marked, Function
gtk:calendar-mark-day, Function
gtk:calendar-month, Accessor
gtk:calendar-new, Function
gtk:calendar-select-day, Function
gtk:calendar-show-day-names, Accessor
gtk:calendar-show-heading, Accessor
gtk:calendar-show-week-numbers, Accessor
gtk:calendar-unmark-day, Function
gtk:calendar-year, Accessor
gtk:callback-action-new, Function
gtk:cell-area-activate, Function
gtk:cell-area-activate-cell, Function
gtk:cell-area-add, Function
gtk:cell-area-add-focus-sibling, Function
gtk:cell-area-add-with-properties, Function
gtk:cell-area-apply-attributes, Function
gtk:cell-area-attribute-column, Function
gtk:cell-area-attribute-connect, Function
gtk:cell-area-attribute-disconnect, Function
gtk:cell-area-box-new, Function
gtk:cell-area-box-pack-end, Function
gtk:cell-area-box-pack-start, Function
gtk:cell-area-box-spacing, Accessor
gtk:cell-area-cell-allocation, Function
gtk:cell-area-cell-at-position, Function
gtk:cell-area-cell-get, Function
gtk:cell-area-cell-property, Function
gtk:cell-area-cell-set, Function
gtk:cell-area-class-find-cell-property, Function
gtk:cell-area-class-list-cell-properties, Function
gtk:cell-area-context-allocate, Function
gtk:cell-area-context-allocation, Function
gtk:cell-area-context-area, Accessor
gtk:cell-area-context-minimum-height, Accessor
gtk:cell-area-context-minimum-width, Accessor
gtk:cell-area-context-natural-height, Accessor
gtk:cell-area-context-natural-width, Accessor
gtk:cell-area-context-preferred-height, Function
gtk:cell-area-context-preferred-height-for-width, Function
gtk:cell-area-context-preferred-width, Function
gtk:cell-area-context-preferred-width-for-height, Function
gtk:cell-area-context-push-preferred-height, Function
gtk:cell-area-context-push-preferred-width, Function
gtk:cell-area-context-reset, Function
gtk:cell-area-copy-context, Function
gtk:cell-area-create-context, Function
gtk:cell-area-current-path-string, Function
gtk:cell-area-edit-widget, Accessor
gtk:cell-area-edited-cell, Accessor
gtk:cell-area-event, Function
gtk:cell-area-focus, Function
gtk:cell-area-focus-cell, Accessor
gtk:cell-area-focus-from-sibling, Function
gtk:cell-area-focus-siblings, Function
gtk:cell-area-foreach, Function
gtk:cell-area-foreach-alloc, Function
gtk:cell-area-has-renderer, Function
gtk:cell-area-inner-cell-area, Function
gtk:cell-area-is-activatable, Function
gtk:cell-area-is-focus-sibling, Function
gtk:cell-area-preferred-height, Function
gtk:cell-area-preferred-height-for-width, Function
gtk:cell-area-preferred-width, Function
gtk:cell-area-preferred-width-for-height, Function
gtk:cell-area-remove, Function
gtk:cell-area-remove-focus-sibling, Function
gtk:cell-area-request-mode, Function
gtk:cell-area-request-renderer, Function
gtk:cell-area-snapshot, Function
gtk:cell-area-stop-editing, Function
gtk:cell-editable-editing-canceled, Accessor
gtk:cell-editable-editing-done, Function
gtk:cell-editable-remove-widget, Function
gtk:cell-editable-start-editing, Function
gtk:cell-layout-add-attribute, Function
gtk:cell-layout-area, Function
gtk:cell-layout-cells, Function
gtk:cell-layout-clear, Function
gtk:cell-layout-clear-attributes, Function
gtk:cell-layout-pack-end, Function
gtk:cell-layout-pack-start, Function
gtk:cell-layout-reorder, Function
gtk:cell-layout-set-attributes, Function
gtk:cell-layout-set-cell-data-func, Function
gtk:cell-renderer-accel-accel-key, Accessor
gtk:cell-renderer-accel-accel-mode, Accessor
gtk:cell-renderer-accel-accel-mods, Accessor
gtk:cell-renderer-accel-keycode, Accessor
gtk:cell-renderer-accel-new, Function
gtk:cell-renderer-activate, Function
gtk:cell-renderer-aligned-area, Function
gtk:cell-renderer-alignment, Function
gtk:cell-renderer-cell-background, Accessor
gtk:cell-renderer-cell-background-rgba, Accessor
gtk:cell-renderer-cell-background-set, Accessor
gtk:cell-renderer-combo-has-entry, Accessor
gtk:cell-renderer-combo-model, Accessor
gtk:cell-renderer-combo-new, Function
gtk:cell-renderer-combo-text-column, Accessor
gtk:cell-renderer-editing, Accessor
gtk:cell-renderer-fixed-size, Function
gtk:cell-renderer-height, Accessor
gtk:cell-renderer-is-activatable, Function
gtk:cell-renderer-is-expanded, Accessor
gtk:cell-renderer-is-expander, Accessor
gtk:cell-renderer-mode, Accessor
gtk:cell-renderer-padding, Function
gtk:cell-renderer-pixbuf-gicon, Accessor
gtk:cell-renderer-pixbuf-icon-name, Accessor
gtk:cell-renderer-pixbuf-icon-size, Accessor
gtk:cell-renderer-pixbuf-new, Function
gtk:cell-renderer-pixbuf-pixbuf, Accessor
gtk:cell-renderer-pixbuf-pixbuf-expander-closed, Accessor
gtk:cell-renderer-pixbuf-pixbuf-expander-open, Accessor
gtk:cell-renderer-pixbuf-texture, Generic Function
gtk:cell-renderer-preferred-height, Function
gtk:cell-renderer-preferred-height-for-width, Function
gtk:cell-renderer-preferred-size, Function
gtk:cell-renderer-preferred-width, Function
gtk:cell-renderer-preferred-width-for-height, Function
gtk:cell-renderer-progress-inverted, Accessor
gtk:cell-renderer-progress-new, Function
gtk:cell-renderer-progress-pulse, Accessor
gtk:cell-renderer-progress-text, Accessor
gtk:cell-renderer-progress-text-xalign, Accessor
gtk:cell-renderer-progress-text-yalign, Accessor
gtk:cell-renderer-progress-value, Accessor
gtk:cell-renderer-request-mode, Function
gtk:cell-renderer-sensitive, Accessor
gtk:cell-renderer-snapshot, Function
gtk:cell-renderer-spin-adjustment, Accessor
gtk:cell-renderer-spin-climb-rate, Accessor
gtk:cell-renderer-spin-digits, Accessor
gtk:cell-renderer-spin-new, Function
gtk:cell-renderer-spinner-active, Accessor
gtk:cell-renderer-spinner-new, Function
gtk:cell-renderer-spinner-pulse, Accessor
gtk:cell-renderer-spinner-size, Accessor
gtk:cell-renderer-start-editing, Function
gtk:cell-renderer-state, Function
gtk:cell-renderer-stop-editing, Function
gtk:cell-renderer-text-align-set, Accessor
gtk:cell-renderer-text-alignment, Accessor
gtk:cell-renderer-text-attributes, Accessor
gtk:cell-renderer-text-background, Accessor
gtk:cell-renderer-text-background-rgba, Accessor
gtk:cell-renderer-text-background-set, Accessor
gtk:cell-renderer-text-editable, Accessor
gtk:cell-renderer-text-editable-set, Accessor
gtk:cell-renderer-text-ellipsize, Accessor
gtk:cell-renderer-text-ellipsize-set, Accessor
gtk:cell-renderer-text-family, Accessor
gtk:cell-renderer-text-family-set, Accessor
gtk:cell-renderer-text-font, Accessor
gtk:cell-renderer-text-font-desc, Accessor
gtk:cell-renderer-text-foreground, Accessor
gtk:cell-renderer-text-foreground-rgba, Accessor
gtk:cell-renderer-text-foreground-set, Accessor
gtk:cell-renderer-text-language, Accessor
gtk:cell-renderer-text-language-set, Accessor
gtk:cell-renderer-text-markup, Accessor
gtk:cell-renderer-text-max-width-chars, Accessor
gtk:cell-renderer-text-new, Function
gtk:cell-renderer-text-placeholder-text, Accessor
gtk:cell-renderer-text-rise, Accessor
gtk:cell-renderer-text-rise-set, Accessor
gtk:cell-renderer-text-scale, Accessor
gtk:cell-renderer-text-scale-set, Accessor
gtk:cell-renderer-text-set-fixed-height-from-font, Function
gtk:cell-renderer-text-single-paragraph-mode, Accessor
gtk:cell-renderer-text-size, Accessor
gtk:cell-renderer-text-size-points, Accessor
gtk:cell-renderer-text-size-set, Accessor
gtk:cell-renderer-text-stretch, Accessor
gtk:cell-renderer-text-stretch-set, Accessor
gtk:cell-renderer-text-strikethrough, Accessor
gtk:cell-renderer-text-strikethrough-set, Accessor
gtk:cell-renderer-text-style, Accessor
gtk:cell-renderer-text-style-set, Accessor
gtk:cell-renderer-text-text, Accessor
gtk:cell-renderer-text-underline, Accessor
gtk:cell-renderer-text-underline-set, Accessor
gtk:cell-renderer-text-variant, Accessor
gtk:cell-renderer-text-variant-set, Accessor
gtk:cell-renderer-text-weight, Accessor
gtk:cell-renderer-text-weight-set, Accessor
gtk:cell-renderer-text-width-chars, Accessor
gtk:cell-renderer-text-wrap-mode, Accessor
gtk:cell-renderer-text-wrap-width, Accessor
gtk:cell-renderer-toggle-activatable, Accessor
gtk:cell-renderer-toggle-active, Accessor
gtk:cell-renderer-toggle-inconsistent, Accessor
gtk:cell-renderer-toggle-new, Function
gtk:cell-renderer-toggle-radio, Accessor
gtk:cell-renderer-visible, Accessor
gtk:cell-renderer-width, Accessor
gtk:cell-renderer-xalign, Accessor
gtk:cell-renderer-xpad, Accessor
gtk:cell-renderer-yalign, Accessor
gtk:cell-renderer-ypad, Accessor
gtk:cell-view-cell-area, Accessor
gtk:cell-view-cell-area-context, Accessor
gtk:cell-view-displayed-row, Function
gtk:cell-view-draw-sensitive, Accessor
gtk:cell-view-fit-model, Accessor
gtk:cell-view-model, Accessor
gtk:cell-view-new, Function
gtk:cell-view-new-with-context, Function
gtk:cell-view-new-with-markup, Function
gtk:cell-view-new-with-text, Function
gtk:cell-view-new-with-texture, Function
gtk:center-box-baseline-position, Accessor
gtk:center-box-center-widget, Accessor
gtk:center-box-end-widget, Accessor
gtk:center-box-new, Function
gtk:center-box-shrink-center-last, Accessor
gtk:center-box-start-widget, Accessor
gtk:center-layout-baseline-position, Function
gtk:center-layout-center-widget, Function
gtk:center-layout-end-widget, Function
gtk:center-layout-new, Function
gtk:center-layout-orientation, Function
gtk:center-layout-shrink-center-last, Accessor
gtk:center-layout-start-widget, Function
gtk:check-button-active, Accessor
gtk:check-button-child, Accessor
gtk:check-button-group, Accessor
gtk:check-button-inconsistent, Accessor
gtk:check-button-label, Accessor
gtk:check-button-new, Function
gtk:check-button-new-with-label, Function
gtk:check-button-new-with-mnemonic, Function
gtk:check-button-use-underline, Accessor
gtk:check-version, Function
gtk:cl-cffi-gtk-build-info, Function
gtk:color-button-modal, Accessor
gtk:color-button-new, Function
gtk:color-button-new-with-rgba, Function
gtk:color-button-show-editor, Accessor
gtk:color-button-title, Accessor
gtk:color-chooser-add-palette, Function
gtk:color-chooser-dialog-new, Function
gtk:color-chooser-dialog-show-editor, Accessor
gtk:color-chooser-rgba, Accessor
gtk:color-chooser-use-alpha, Accessor
gtk:color-chooser-widget-new, Function
gtk:color-chooser-widget-show-editor, Accessor
gtk:color-dialog-button-dialog, Accessor
gtk:color-dialog-button-new, Function
gtk:color-dialog-button-rgba, Accessor
gtk:color-dialog-choose-rgba, Function
gtk:color-dialog-choose-rgba-finish, Function
gtk:color-dialog-modal, Accessor
gtk:color-dialog-new, Function
gtk:color-dialog-title, Accessor
gtk:color-dialog-with-alpha, Accessor
gtk:column-view-append-column, Function
gtk:column-view-cell-child, Accessor
gtk:column-view-cell-focusable, Accessor
gtk:column-view-cell-item, Accessor
gtk:column-view-cell-position, Accessor
gtk:column-view-cell-selected, Accessor
gtk:column-view-column-column-view, Accessor
gtk:column-view-column-expand, Accessor
gtk:column-view-column-factory, Accessor
gtk:column-view-column-fixed-width, Accessor
gtk:column-view-column-header-menu, Accessor
gtk:column-view-column-id, Accessor
gtk:column-view-column-new, Function
gtk:column-view-column-resizable, Accessor
gtk:column-view-column-sorter, Accessor
gtk:column-view-column-title, Accessor
gtk:column-view-column-visible, Accessor
gtk:column-view-columns, Accessor
gtk:column-view-enable-rubberband, Accessor
gtk:column-view-header-factory, Accessor
gtk:column-view-insert-column, Function
gtk:column-view-model, Accessor
gtk:column-view-new, Function
gtk:column-view-remove-column, Function
gtk:column-view-reorderable, Accessor
gtk:column-view-row-accessible-description, Accessor
gtk:column-view-row-accessible-label, Accessor
gtk:column-view-row-activatable, Accessor
gtk:column-view-row-factory, Accessor
gtk:column-view-row-focusable, Accessor
gtk:column-view-row-item, Accessor
gtk:column-view-row-position, Accessor
gtk:column-view-row-selectable, Accessor
gtk:column-view-row-selected, Accessor
gtk:column-view-show-column-separators, Accessor
gtk:column-view-show-row-separators, Accessor
gtk:column-view-single-click-activate, Accessor
gtk:column-view-sort-by-column, Function
gtk:column-view-sorter, Accessor
gtk:column-view-sorter-n-sort-columns, Function
gtk:column-view-sorter-nth-sort-column, Function
gtk:column-view-sorter-primary-sort-column, Accessor
gtk:column-view-sorter-primary-sort-order, Accessor
gtk:column-view-tab-behavior, Accessor
gtk:combo-box-active, Accessor
gtk:combo-box-active-id, Accessor
gtk:combo-box-active-iter, Function
gtk:combo-box-button-sensitivity, Accessor
gtk:combo-box-child, Accessor
gtk:combo-box-entry-text-column, Accessor
gtk:combo-box-has-entry, Accessor
gtk:combo-box-has-frame, Accessor
gtk:combo-box-id-column, Accessor
gtk:combo-box-model, Accessor
gtk:combo-box-new, Function
gtk:combo-box-new-with-entry, Function
gtk:combo-box-new-with-model, Function
gtk:combo-box-new-with-model-and-entry, Function
gtk:combo-box-popdown, Function
gtk:combo-box-popup, Function
gtk:combo-box-popup-fixed-width, Accessor
gtk:combo-box-popup-for-device, Function
gtk:combo-box-popup-shown, Accessor
gtk:combo-box-set-row-separator-func, Function
gtk:combo-box-text-active-text, Function
gtk:combo-box-text-append, Function
gtk:combo-box-text-append-text, Function
gtk:combo-box-text-insert, Function
gtk:combo-box-text-insert-text, Function
gtk:combo-box-text-new, Function
gtk:combo-box-text-new-with-entry, Function
gtk:combo-box-text-prepend, Function
gtk:combo-box-text-prepend-text, Function
gtk:combo-box-text-remove, Function
gtk:combo-box-text-remove-all, Function
gtk:constant-expression-new, Function
gtk:constant-expression-new-for-value, Function
gtk:constant-expression-value, Function
gtk:constraint-constant, Accessor
gtk:constraint-guide-max-height, Accessor
gtk:constraint-guide-max-width, Accessor
gtk:constraint-guide-min-height, Accessor
gtk:constraint-guide-min-width, Accessor
gtk:constraint-guide-name, Accessor
gtk:constraint-guide-nat-height, Accessor
gtk:constraint-guide-nat-width, Accessor
gtk:constraint-guide-new, Function
gtk:constraint-guide-strength, Accessor
gtk:constraint-is-attached, Function
gtk:constraint-is-constant, Function
gtk:constraint-is-required, Function
gtk:constraint-layout-add-constraint, Function
gtk:constraint-layout-add-guide, Function
gtk:constraint-layout-new, Function
gtk:constraint-layout-remove-all-constraints, Function
gtk:constraint-layout-remove-constraint, Function
gtk:constraint-layout-remove-guide, Function
gtk:constraint-multiplier, Accessor
gtk:constraint-new, Function
gtk:constraint-new-constant, Function
gtk:constraint-relation, Accessor
gtk:constraint-source, Accessor
gtk:constraint-source-attribute, Accessor
gtk:constraint-strength, Accessor
gtk:constraint-target, Accessor
gtk:constraint-target-attribute, Accessor
gtk:css-location-bytes, Accessor
gtk:css-location-chars, Accessor
gtk:css-location-line-bytes, Accessor
gtk:css-location-line-chars, Accessor
gtk:css-location-lines, Accessor
gtk:css-provider-load-from-bytes, Function
gtk:css-provider-load-from-data, Function
gtk:css-provider-load-from-file, Function
gtk:css-provider-load-from-path, Function
gtk:css-provider-load-from-resource, Function
gtk:css-provider-load-from-string, Function
gtk:css-provider-load-named, Function
gtk:css-provider-new, Function
gtk:css-provider-to-string, Function
gtk:css-section-bytes, Function
gtk:css-section-end-location, Function
gtk:css-section-file, Function
gtk:css-section-new, Function
gtk:css-section-new-with-bytes, Function
gtk:css-section-parent, Function
gtk:css-section-start-location, Function
gtk:css-section-to-string, Function
gtk:custom-filter-new, Function
gtk:custom-filter-set-filter-func, Function
gtk:custom-sorter-new, Function
gtk:custom-sorter-set-sort-func, Function
gtk:default-language, Function
gtk:dialog-add-action-widget, Function
gtk:dialog-add-button, Function
gtk:dialog-add-buttons, Function
gtk:dialog-content-area, Function
gtk:dialog-header-bar, Function
gtk:dialog-new, Function
gtk:dialog-new-with-buttons, Function
gtk:dialog-response, Function
gtk:dialog-response-for-widget, Function
gtk:dialog-set-default-response, Function
gtk:dialog-set-response-sensitive, Function
gtk:dialog-use-header-bar, Accessor
gtk:dialog-widget-for-response, Function
gtk:directory-list-attributes, Accessor
gtk:directory-list-error, Accessor
gtk:directory-list-file, Accessor
gtk:directory-list-io-priority, Accessor
gtk:directory-list-is-loading, Function
gtk:directory-list-item-type, Accessor
gtk:directory-list-loading, Accessor
gtk:directory-list-monitored, Accessor
gtk:directory-list-n-items, Accessor
gtk:directory-list-new, Function
gtk:disable-setlocale, Function
gtk:drag-check-threshold, Function
gtk:drag-icon-child, Accessor
gtk:drag-icon-create-widget-for-value, Function
gtk:drag-icon-for-drag, Function
gtk:drag-icon-set-from-paintable, Function
gtk:drag-source-actions, Accessor
gtk:drag-source-content, Accessor
gtk:drag-source-drag, Function
gtk:drag-source-drag-cancel, Function
gtk:drag-source-new, Function
gtk:drag-source-set-icon, Function
gtk:drawing-area-content-height, Accessor
gtk:drawing-area-content-width, Accessor
gtk:drawing-area-new, Function
gtk:drawing-area-set-draw-func, Function
gtk:drop-controller-motion-contains-pointer, Accessor
gtk:drop-controller-motion-drop, Accessor
gtk:drop-controller-motion-is-pointer, Accessor
gtk:drop-controller-motion-new, Function
gtk:drop-down-enable-search, Accessor
gtk:drop-down-expression, Accessor
gtk:drop-down-factory, Accessor
gtk:drop-down-header-factory, Accessor
gtk:drop-down-list-factory, Accessor
gtk:drop-down-model, Accessor
gtk:drop-down-new, Function
gtk:drop-down-new-from-strings, Function
gtk:drop-down-search-match-mode, Accessor
gtk:drop-down-selected, Accessor
gtk:drop-down-selected-item, Accessor
gtk:drop-down-show-arrow, Accessor
gtk:drop-target-actions, Accessor
gtk:drop-target-async-actions, Accessor
gtk:drop-target-async-formats, Accessor
gtk:drop-target-async-new, Function
gtk:drop-target-async-reject-drop, Function
gtk:drop-target-current-drop, Accessor
gtk:drop-target-drop, Accessor
gtk:drop-target-formats, Accessor
gtk:drop-target-gtypes, Function
gtk:drop-target-new, Function
gtk:drop-target-preload, Accessor
gtk:drop-target-reject, Function
gtk:drop-target-value, Accessor
gtk:editable-alignment, Function
gtk:editable-chars, Function
gtk:editable-cursor-position, Accessor
gtk:editable-delete-selection, Function
gtk:editable-delete-text, Function
gtk:editable-editable, Accessor
gtk:editable-enable-undo, Accessor
gtk:editable-insert-text, Function
gtk:editable-label-editing, Accessor
gtk:editable-label-new, Function
gtk:editable-label-start-editing, Function
gtk:editable-label-stop-editing, Function
gtk:editable-max-width-chars, Accessor
gtk:editable-position, Function
gtk:editable-select-region, Function
gtk:editable-selection-bound, Accessor
gtk:editable-selection-bounds, Function
gtk:editable-text, Accessor
gtk:editable-width-chars, Accessor
gtk:editable-xalign, Accessor
gtk:emoji-chooser-new, Function
gtk:entry-activates-default, Accessor
gtk:entry-alignment, Function
gtk:entry-attributes, Accessor
gtk:entry-buffer, Accessor
gtk:entry-buffer-bytes, Function
gtk:entry-buffer-delete-text, Function
gtk:entry-buffer-emit-deleted-text, Function
gtk:entry-buffer-emit-inserted-text, Function
gtk:entry-buffer-insert-text, Function
gtk:entry-buffer-length, Accessor
gtk:entry-buffer-max-length, Accessor
gtk:entry-buffer-new, Function
gtk:entry-buffer-text, Accessor
gtk:entry-completion, Accessor
gtk:entry-completion-cell-area, Accessor
gtk:entry-completion-complete, Function
gtk:entry-completion-completion-prefix, Function
gtk:entry-completion-compute-prefix, Function
gtk:entry-completion-entry, Function
gtk:entry-completion-inline-completion, Accessor
gtk:entry-completion-inline-selection, Accessor
gtk:entry-completion-insert-prefix, Function
gtk:entry-completion-minimum-key-length, Accessor
gtk:entry-completion-model, Accessor
gtk:entry-completion-new, Function
gtk:entry-completion-new-with-area, Function
gtk:entry-completion-popup-completion, Accessor
gtk:entry-completion-popup-set-width, Accessor
gtk:entry-completion-popup-single-match, Accessor
gtk:entry-completion-set-match-func, Function
gtk:entry-completion-text-column, Accessor
gtk:entry-current-icon-drag-source, Function
gtk:entry-enable-emoji-completion, Accessor
gtk:entry-extra-menu, Accessor
gtk:entry-grab-focus-without-selecting, Function
gtk:entry-has-frame, Accessor
gtk:entry-icon-activatable, Function
gtk:entry-icon-area, Function
gtk:entry-icon-at-pos, Function
gtk:entry-icon-gicon, Function
gtk:entry-icon-name, Function
gtk:entry-icon-paintable, Function
gtk:entry-icon-sensitive, Function
gtk:entry-icon-storage-type, Function
gtk:entry-icon-tooltip-markup, Function
gtk:entry-icon-tooltip-text, Function
gtk:entry-im-module, Accessor
gtk:entry-input-hints, Accessor
gtk:entry-input-purpose, Accessor
gtk:entry-invisible-char, Accessor
gtk:entry-invisible-char-set, Accessor
gtk:entry-max-length, Accessor
gtk:entry-new, Function
gtk:entry-new-with-buffer, Function
gtk:entry-overwrite-mode, Accessor
gtk:entry-placeholder-text, Accessor
gtk:entry-primary-icon-activatable, Accessor
gtk:entry-primary-icon-gicon, Accessor
gtk:entry-primary-icon-name, Accessor
gtk:entry-primary-icon-paintable, Accessor
gtk:entry-primary-icon-sensitive, Accessor
gtk:entry-primary-icon-storage-type, Accessor
gtk:entry-primary-icon-tooltip-markup, Accessor
gtk:entry-primary-icon-tooltip-text, Accessor
gtk:entry-progress-fraction, Accessor
gtk:entry-progress-pulse, Function
gtk:entry-progress-pulse-step, Accessor
gtk:entry-reset-im-context, Function
gtk:entry-scroll-offset, Accessor
gtk:entry-secondary-icon-activatable, Accessor
gtk:entry-secondary-icon-gicon, Accessor
gtk:entry-secondary-icon-name, Accessor
gtk:entry-secondary-icon-paintable, Accessor
gtk:entry-secondary-icon-sensitive, Accessor
gtk:entry-secondary-icon-storage-type, Accessor
gtk:entry-secondary-icon-tooltip-markup, Accessor
gtk:entry-secondary-icon-tooltip-text, Accessor
gtk:entry-set-icon-drag-source, Function
gtk:entry-set-icon-from-gicon, Function
gtk:entry-set-icon-from-icon-name, Function
gtk:entry-set-icon-from-paintable, Function
gtk:entry-show-emoji-icon, Accessor
gtk:entry-tabs, Accessor
gtk:entry-text-length, Accessor
gtk:entry-truncate-multiline, Accessor
gtk:entry-unset-invisible-char, Function
gtk:entry-visibility, Accessor
gtk:enumerate-printers, Function
gtk:event-controller-current-event, Function
gtk:event-controller-current-event-device, Function
gtk:event-controller-current-event-state, Function
gtk:event-controller-current-event-time, Function
gtk:event-controller-focus-contains-focus, Accessor
gtk:event-controller-focus-is-focus, Accessor
gtk:event-controller-focus-new, Function
gtk:event-controller-key-forward, Function
gtk:event-controller-key-group, Function
gtk:event-controller-key-im-context, Function
gtk:event-controller-key-new, Function
gtk:event-controller-legacy-new, Function
gtk:event-controller-motion-contains-pointer, Accessor
gtk:event-controller-motion-is-pointer, Accessor
gtk:event-controller-motion-new, Function
gtk:event-controller-name, Accessor
gtk:event-controller-propagation-limit, Accessor
gtk:event-controller-propagation-phase, Accessor
gtk:event-controller-reset, Function
gtk:event-controller-scroll-flags, Accessor
gtk:event-controller-scroll-new, Function
gtk:event-controller-scroll-unit, Function
gtk:event-controller-widget, Accessor
gtk:every-filter-new, Function
gtk:expander-child, Accessor
gtk:expander-expanded, Accessor
gtk:expander-label, Accessor
gtk:expander-label-widget, Accessor
gtk:expander-new, Function
gtk:expander-new-with-mnemonic, Function
gtk:expander-resize-toplevel, Accessor
gtk:expander-use-markup, Accessor
gtk:expander-use-underline, Accessor
gtk:expression-bind, Function
gtk:expression-evaluate, Function
gtk:expression-evaluate-value, Function
gtk:expression-is-static, Function
gtk:expression-ref, Function
gtk:expression-unref, Function
gtk:expression-value-type, Function
gtk:expression-watch, Function
gtk:expression-watch-evaluate, Function
gtk:expression-watch-evaluate-value, Function
gtk:expression-watch-unwatch, Function
gtk:file-chooser-action, Accessor
gtk:file-chooser-add-filter, Function
gtk:file-chooser-add-shortcut-folder, Function
gtk:file-chooser-create-folders, Accessor
gtk:file-chooser-current-folder, Function
gtk:file-chooser-current-name, Function
gtk:file-chooser-dialog-new, Function
gtk:file-chooser-file, Function
gtk:file-chooser-files, Function
gtk:file-chooser-filter, Accessor
gtk:file-chooser-filters, Accessor
gtk:file-chooser-namestring, Function
gtk:file-chooser-native-accept-label, Accessor
gtk:file-chooser-native-cancel-label, Accessor
gtk:file-chooser-native-new, Function
gtk:file-chooser-remove-filter, Function
gtk:file-chooser-remove-shortcut-folder, Function
gtk:file-chooser-select-multiple, Accessor
gtk:file-chooser-shortcut-folders, Accessor
gtk:file-chooser-widget-new, Function
gtk:file-chooser-widget-search-mode, Accessor
gtk:file-chooser-widget-show-time, Accessor
gtk:file-chooser-widget-subtitle, Accessor
gtk:file-dialog-accept-label, Accessor
gtk:file-dialog-default-filter, Accessor
gtk:file-dialog-filters, Accessor
gtk:file-dialog-initial-file, Accessor
gtk:file-dialog-initial-folder, Accessor
gtk:file-dialog-initial-name, Accessor
gtk:file-dialog-modal, Accessor
gtk:file-dialog-new, Function
gtk:file-dialog-open, Function
gtk:file-dialog-open-finish, Function
gtk:file-dialog-open-multiple, Function
gtk:file-dialog-open-multiple-finish, Function
gtk:file-dialog-save, Function
gtk:file-dialog-save-finish, Function
gtk:file-dialog-select-folder, Function
gtk:file-dialog-select-folder-finish, Function
gtk:file-dialog-select-multiple-folders, Function
gtk:file-dialog-select-multiple-folders-finish, Function
gtk:file-dialog-title, Accessor
gtk:file-filter-add-mime-type, Function
gtk:file-filter-add-pattern, Function
gtk:file-filter-add-pixbuf-formats, Function
gtk:file-filter-add-suffix, Function
gtk:file-filter-attributes, Function
gtk:file-filter-name, Accessor
gtk:file-filter-new, Function
gtk:file-filter-new-from-gvariant, Function
gtk:file-filter-to-gvariant, Function
gtk:file-launcher-always-ask, Accessor
gtk:file-launcher-file, Accessor
gtk:file-launcher-launch, Function
gtk:file-launcher-launch-finish, Function
gtk:file-launcher-new, Function
gtk:file-launcher-open-containing-folder, Function
gtk:file-launcher-open-containing-folder-finish, Function
gtk:file-launcher-writable, Accessor
gtk:filter-changed, Function
gtk:filter-list-model-filter, Accessor
gtk:filter-list-model-incremental, Accessor
gtk:filter-list-model-item-type, Accessor
gtk:filter-list-model-model, Accessor
gtk:filter-list-model-n-items, Accessor
gtk:filter-list-model-new, Function
gtk:filter-list-model-pending, Accessor
gtk:filter-match, Function
gtk:filter-strictness, Function
gtk:fixed-child-position, Function
gtk:fixed-child-transform, Function
gtk:fixed-layout-child-transform, Accessor
gtk:fixed-layout-new, Function
gtk:fixed-move, Function
gtk:fixed-new, Function
gtk:fixed-put, Function
gtk:fixed-remove, Function
gtk:flatten-list-model-item-type, Accessor
gtk:flatten-list-model-model, Accessor
gtk:flatten-list-model-model-for-item, Function
gtk:flatten-list-model-n-items, Accessor
gtk:flatten-list-model-new, Function
gtk:flow-box-accept-unpaired-release, Accessor
gtk:flow-box-activate-on-single-click, Accessor
gtk:flow-box-append, Function
gtk:flow-box-bind-model, Function
gtk:flow-box-child-at-index, Function
gtk:flow-box-child-at-pos, Function
gtk:flow-box-child-changed, Function
gtk:flow-box-child-child, Accessor
gtk:flow-box-child-index, Function
gtk:flow-box-child-is-selected, Function
gtk:flow-box-child-new, Function
gtk:flow-box-column-spacing, Accessor
gtk:flow-box-homogeneous, Accessor
gtk:flow-box-insert, Function
gtk:flow-box-invalidate-filter, Function
gtk:flow-box-invalidate-sort, Function
gtk:flow-box-max-children-per-line, Accessor
gtk:flow-box-min-children-per-line, Accessor
gtk:flow-box-new, Function
gtk:flow-box-prepend, Function
gtk:flow-box-remove, Function
gtk:flow-box-remove-all, Function
gtk:flow-box-row-spacing, Accessor
gtk:flow-box-select-all, Function
gtk:flow-box-select-child, Function
gtk:flow-box-selected-children, Function
gtk:flow-box-selected-foreach, Function
gtk:flow-box-selection-mode, Accessor
gtk:flow-box-set-filter-func, Function
gtk:flow-box-set-hadjustment, Function
gtk:flow-box-set-sort-func, Function
gtk:flow-box-set-vadjustment, Function
gtk:flow-box-unselect-all, Function
gtk:flow-box-unselect-child, Function
gtk:font-button-modal, Accessor
gtk:font-button-new, Function
gtk:font-button-new-with-font, Function
gtk:font-button-title, Accessor
gtk:font-button-use-font, Accessor
gtk:font-button-use-size, Accessor
gtk:font-chooser-dialog-new, Function
gtk:font-chooser-font, Accessor
gtk:font-chooser-font-desc, Accessor
gtk:font-chooser-font-face, Function
gtk:font-chooser-font-family, Function
gtk:font-chooser-font-features, Accessor
gtk:font-chooser-font-map, Function
gtk:font-chooser-font-size, Function
gtk:font-chooser-language, Accessor
gtk:font-chooser-level, Accessor
gtk:font-chooser-preview-text, Accessor
gtk:font-chooser-set-filter-func, Function
gtk:font-chooser-show-preview-entry, Accessor
gtk:font-chooser-widget-new, Function
gtk:font-chooser-widget-tweak-action, Accessor
gtk:font-dialog-button-dialog, Accessor
gtk:font-dialog-button-font-desc, Accessor
gtk:font-dialog-button-font-features, Accessor
gtk:font-dialog-button-language, Accessor
gtk:font-dialog-button-level, Accessor
gtk:font-dialog-button-new, Function
gtk:font-dialog-button-use-font, Accessor
gtk:font-dialog-button-use-size, Accessor
gtk:font-dialog-choose-face, Function
gtk:font-dialog-choose-face-finish, Function
gtk:font-dialog-choose-family, Function
gtk:font-dialog-choose-family-finish, Function
gtk:font-dialog-choose-font, Function
gtk:font-dialog-choose-font-and-features, Function
gtk:font-dialog-choose-font-and-features-finish, Function
gtk:font-dialog-choose-font-finish, Function
gtk:font-dialog-filter, Accessor
gtk:font-dialog-font-map, Accessor
gtk:font-dialog-language, Accessor
gtk:font-dialog-modal, Accessor
gtk:font-dialog-new, Function
gtk:font-dialog-title, Accessor
gtk:frame-child, Accessor
gtk:frame-label, Accessor
gtk:frame-label-align, Function
gtk:frame-label-widget, Accessor
gtk:frame-label-xalign, Accessor
gtk:frame-new, Function
gtk:gesture-bounding-box, Function
gtk:gesture-bounding-box-center, Function
gtk:gesture-click-new, Function
gtk:gesture-device, Function
gtk:gesture-drag-new, Function
gtk:gesture-drag-offset, Function
gtk:gesture-drag-start-point, Function
gtk:gesture-get-group, Function
gtk:gesture-group, Function
gtk:gesture-handles-sequence, Function
gtk:gesture-is-active, Function
gtk:gesture-is-grouped-with, Function
gtk:gesture-is-recognized, Function
gtk:gesture-last-event, Function
gtk:gesture-last-updated-sequence, Function
gtk:gesture-long-press-delay-factor, Accessor
gtk:gesture-long-press-new, Function
gtk:gesture-n-points, Accessor
gtk:gesture-pan-new, Function
gtk:gesture-pan-orientation, Accessor
gtk:gesture-point, Function
gtk:gesture-rotate-angle-delta, Function
gtk:gesture-rotate-new, Function
gtk:gesture-sequence-state, Function
gtk:gesture-sequences, Function
gtk:gesture-set-state, Function
gtk:gesture-single-button, Accessor
gtk:gesture-single-current-button, Function
gtk:gesture-single-current-sequence, Function
gtk:gesture-single-exclusive, Accessor
gtk:gesture-single-touch-only, Accessor
gtk:gesture-stylus-axis, Function
gtk:gesture-stylus-device-tool, Function
gtk:gesture-stylus-new, Function
gtk:gesture-stylus-stylus-only, Accessor
gtk:gesture-swipe-new, Function
gtk:gesture-swipe-velocity, Function
gtk:gesture-ungroup, Function
gtk:gesture-zoom-new, Function
gtk:gesture-zoom-scale-delta, Function
gtk:gl-area-allowed-apis, Accessor
gtk:gl-area-api, Accessor
gtk:gl-area-attach-buffers, Function
gtk:gl-area-auto-render, Accessor
gtk:gl-area-context, Accessor
gtk:gl-area-has-depth-buffer, Accessor
gtk:gl-area-has-stencil-buffer, Accessor
gtk:gl-area-make-current, Function
gtk:gl-area-new, Function
gtk:gl-area-queue-render, Function
gtk:gl-area-required-version, Function
gtk:gl-area-use-es, Accessor
gtk:graphics-offload-black-background, Accessor
gtk:graphics-offload-child, Accessor
gtk:graphics-offload-enabled, Accessor
gtk:graphics-offload-new, Function
gtk:grid-attach, Function
gtk:grid-attach-next-to, Function
gtk:grid-baseline-row, Accessor
gtk:grid-child-at, Function
gtk:grid-column-homogeneous, Accessor
gtk:grid-column-spacing, Accessor
gtk:grid-insert-column, Function
gtk:grid-insert-next-to, Function
gtk:grid-insert-row, Function
gtk:grid-layout-baseline-row, Accessor
gtk:grid-layout-child-column, Accessor
gtk:grid-layout-child-column-span, Accessor
gtk:grid-layout-child-row, Accessor
gtk:grid-layout-child-row-span, Accessor
gtk:grid-layout-column-homogeneous, Accessor
gtk:grid-layout-column-spacing, Accessor
gtk:grid-layout-new, Function
gtk:grid-layout-row-baseline-position, Function
gtk:grid-layout-row-homogeneous, Accessor
gtk:grid-layout-row-spacing, Accessor
gtk:grid-new, Function
gtk:grid-query-child, Function
gtk:grid-remove, Function
gtk:grid-remove-column, Function
gtk:grid-remove-row, Function
gtk:grid-row-baseline-position, Function
gtk:grid-row-homogeneous, Accessor
gtk:grid-row-spacing, Accessor
gtk:grid-view-enable-rubberband, Accessor
gtk:grid-view-factory, Accessor
gtk:grid-view-max-columns, Accessor
gtk:grid-view-min-columns, Accessor
gtk:grid-view-model, Accessor
gtk:grid-view-new, Function
gtk:grid-view-scroll-to, Function
gtk:grid-view-single-click-activate, Accessor
gtk:grid-view-tab-behavior, Accessor
gtk:header-bar-decoration-layout, Accessor
gtk:header-bar-new, Function
gtk:header-bar-pack-end, Function
gtk:header-bar-pack-start, Function
gtk:header-bar-remove, Function
gtk:header-bar-show-title-buttons, Accessor
gtk:header-bar-title-widget, Accessor
gtk:hsv-to-rgb, Function
gtk:icon-paintable-file, Accessor
gtk:icon-paintable-icon-name, Accessor
gtk:icon-paintable-is-symbolic, Accessor
gtk:icon-paintable-new-for-file, Function
gtk:icon-theme-add-resource-path, Function
gtk:icon-theme-add-search-path, Function
gtk:icon-theme-display, Accessor
gtk:icon-theme-for-display, Function
gtk:icon-theme-has-gicon, Function
gtk:icon-theme-has-icon, Function
gtk:icon-theme-icon-names, Accessor
gtk:icon-theme-icon-sizes, Function
gtk:icon-theme-lookup-by-gicon, Function
gtk:icon-theme-lookup-icon, Function
gtk:icon-theme-new, Function
gtk:icon-theme-resource-path, Accessor
gtk:icon-theme-search-path, Accessor
gtk:icon-theme-theme-name, Accessor
gtk:icon-view-activate-on-single-click, Accessor
gtk:icon-view-cell-area, Accessor
gtk:icon-view-cell-rect, Function
gtk:icon-view-column-spacing, Accessor
gtk:icon-view-columns, Accessor
gtk:icon-view-create-drag-icon, Function
gtk:icon-view-dest-item-at-pos, Function
gtk:icon-view-enable-model-drag-dest, Function
gtk:icon-view-enable-model-drag-source, Function
gtk:icon-view-get-cursor, Function
gtk:icon-view-get-drag-dest-item, Function
gtk:icon-view-item-activated, Function
gtk:icon-view-item-at-pos, Function
gtk:icon-view-item-column, Function
gtk:icon-view-item-orientation, Accessor
gtk:icon-view-item-padding, Accessor
gtk:icon-view-item-row, Function
gtk:icon-view-item-width, Accessor
gtk:icon-view-margin, Accessor
gtk:icon-view-markup-column, Accessor
gtk:icon-view-model, Accessor
gtk:icon-view-new, Function
gtk:icon-view-new-with-area, Function
gtk:icon-view-new-with-model, Function
gtk:icon-view-path-at-pos, Function
gtk:icon-view-path-is-selected, Function
gtk:icon-view-pixbuf-column, Accessor
gtk:icon-view-reorderable, Accessor
gtk:icon-view-row-spacing, Accessor
gtk:icon-view-scroll-to-path, Function
gtk:icon-view-select-all, Function
gtk:icon-view-select-path, Function
gtk:icon-view-selected-foreach, Function
gtk:icon-view-selected-items, Function
gtk:icon-view-selection-mode, Accessor
gtk:icon-view-set-cursor, Function
gtk:icon-view-set-drag-dest-item, Function
gtk:icon-view-set-tooltip-cell, Function
gtk:icon-view-set-tooltip-item, Function
gtk:icon-view-spacing, Accessor
gtk:icon-view-text-column, Accessor
gtk:icon-view-tooltip-column, Accessor
gtk:icon-view-tooltip-context, Function
gtk:icon-view-unselect-all, Function
gtk:icon-view-unselect-path, Function
gtk:icon-view-unset-model-drag-dest, Function
gtk:icon-view-unset-model-drag-source, Function
gtk:icon-view-visible-range, Function
gtk:im-context-filter-keypress, Function
gtk:im-context-input-hints, Accessor
gtk:im-context-input-purpose, Accessor
gtk:im-context-simple-new, Function
gtk:im-multicontext-new, Function
gtk:image-clear, Function
gtk:image-file, Accessor
gtk:image-gicon, Accessor
gtk:image-icon-name, Accessor
gtk:image-icon-size, Accessor
gtk:image-new, Function
gtk:image-new-from-file, Function
gtk:image-new-from-gicon, Function
gtk:image-new-from-icon-name, Function
gtk:image-new-from-paintable, Function
gtk:image-new-from-pixbuf, Function
gtk:image-new-from-resource, Function
gtk:image-paintable, Accessor
gtk:image-pixel-size, Accessor
gtk:image-resource, Accessor
gtk:image-set-from-file, Function
gtk:image-set-from-gicon, Function
gtk:image-set-from-icon-name, Function
gtk:image-set-from-paintable, Function
gtk:image-set-from-pixbuf, Function
gtk:image-set-from-resource, Function
gtk:image-storage-type, Accessor
gtk:image-use-fallback, Accessor
gtk:info-bar-add-action-widget, Function
gtk:info-bar-add-button, Function
gtk:info-bar-add-buttons, Function
gtk:info-bar-add-child, Function
gtk:info-bar-message-type, Accessor
gtk:info-bar-new, Function
gtk:info-bar-new-with-buttons, Function
gtk:info-bar-remove-action-widget, Function
gtk:info-bar-remove-child, Function
gtk:info-bar-response, Function
gtk:info-bar-revealed, Accessor
gtk:info-bar-set-default-response, Function
gtk:info-bar-set-response-sensitive, Function
gtk:info-bar-show-close-button, Accessor
gtk:init, Function
gtk:init-check, Function
gtk:inscription-attributes, Accessor
gtk:inscription-markup, Accessor
gtk:inscription-min-chars, Accessor
gtk:inscription-min-lines, Accessor
gtk:inscription-nat-chars, Accessor
gtk:inscription-nat-lines, Accessor
gtk:inscription-new, Function
gtk:inscription-text, Accessor
gtk:inscription-text-overflow, Accessor
gtk:inscription-wrap-mode, Accessor
gtk:inscription-xalign, Accessor
gtk:inscription-yalign, Accessor
gtk:is-initialized, Function
gtk:keyval-trigger-keyval, Accessor
gtk:keyval-trigger-modifiers, Accessor
gtk:keyval-trigger-new, Function
gtk:label-attributes, Accessor
gtk:label-current-uri, Function
gtk:label-ellipsize, Accessor
gtk:label-extra-menu, Accessor
gtk:label-justify, Accessor
gtk:label-label, Accessor
gtk:label-layout, Function
gtk:label-layout-offsets, Function
gtk:label-lines, Accessor
gtk:label-max-width-chars, Accessor
gtk:label-mnemonic-keyval, Accessor
gtk:label-mnemonic-widget, Accessor
gtk:label-natural-wrap-mode, Accessor
gtk:label-new, Function
gtk:label-new-with-mnemonic, Function
gtk:label-select-region, Function
gtk:label-selectable, Accessor
gtk:label-selection-bounds, Function
gtk:label-set-markup, Function
gtk:label-set-markup-with-mnemonic, Function
gtk:label-set-text-with-mnemonic, Function
gtk:label-single-line-mode, Accessor
gtk:label-tabs, Accessor
gtk:label-text, Function
gtk:label-use-markup, Accessor
gtk:label-use-underline, Accessor
gtk:label-width-chars, Accessor
gtk:label-wrap, Accessor
gtk:label-wrap-mode, Accessor
gtk:label-xalign, Accessor
gtk:label-yalign, Accessor
gtk:layout-child-child-widget, Accessor
gtk:layout-child-layout-manager, Accessor
gtk:layout-manager-allocate, Function
gtk:layout-manager-layout-changed, Function
gtk:layout-manager-layout-child, Function
gtk:layout-manager-measure, Function
gtk:layout-manager-request-mode, Function
gtk:layout-manager-widget, Function
gtk:level-bar-add-offset-value, Function
gtk:level-bar-inverted, Accessor
gtk:level-bar-max-value, Accessor
gtk:level-bar-min-value, Accessor
gtk:level-bar-mode, Accessor
gtk:level-bar-new, Function
gtk:level-bar-new-for-interval, Function
gtk:level-bar-offset-value, Function
gtk:level-bar-remove-offset-value, Function
gtk:level-bar-value, Accessor
gtk:link-button-new, Function
gtk:link-button-new-with-label, Function
gtk:link-button-uri, Accessor
gtk:link-button-visited, Accessor
gtk:list-base-orientation, Accessor
gtk:list-box-accept-unpaired-release, Accessor
gtk:list-box-activate-on-single-click, Accessor
gtk:list-box-adjustment, Function
gtk:list-box-append, Function
gtk:list-box-bind-model, Function
gtk:list-box-drag-highlight-row, Function
gtk:list-box-drag-unhighlight-row, Function
gtk:list-box-insert, Function
gtk:list-box-invalidate-filter, Function
gtk:list-box-invalidate-headers, Function
gtk:list-box-invalidate-sort, Function
gtk:list-box-new, Function
gtk:list-box-prepend, Function
gtk:list-box-remove, Function
gtk:list-box-remove-all, Function
gtk:list-box-row-activatable, Accessor
gtk:list-box-row-at-index, Function
gtk:list-box-row-at-y, Function
gtk:list-box-row-changed, Function
gtk:list-box-row-child, Accessor
gtk:list-box-row-header, Function
gtk:list-box-row-index, Function
gtk:list-box-row-is-selected, Function
gtk:list-box-row-new, Function
gtk:list-box-row-selectable, Accessor
gtk:list-box-select-all, Function
gtk:list-box-select-row, Function
gtk:list-box-selected-foreach, Function
gtk:list-box-selected-row, Function
gtk:list-box-selected-rows, Function
gtk:list-box-selection-mode, Accessor
gtk:list-box-set-filter-func, Function
gtk:list-box-set-header-func, Function
gtk:list-box-set-placeholder, Function
gtk:list-box-set-sort-func, Function
gtk:list-box-show-separators, Accessor
gtk:list-box-unselect-all, Function
gtk:list-box-unselect-row, Function
gtk:list-header-child, Accessor
gtk:list-header-end, Accessor
gtk:list-header-item, Accessor
gtk:list-header-n-items, Accessor
gtk:list-header-start, Accessor
gtk:list-item-accessible-description, Accessor
gtk:list-item-accessible-label, Accessor
gtk:list-item-activatable, Accessor
gtk:list-item-child, Accessor
gtk:list-item-focusable, Accessor
gtk:list-item-item, Accessor
gtk:list-item-position, Accessor
gtk:list-item-selectable, Accessor
gtk:list-item-selected, Accessor
gtk:list-list-model-n-items, Generic Function  (undocumented)
gtk:list-store-append, Function
gtk:list-store-clear, Function
gtk:list-store-insert, Function
gtk:list-store-insert-after, Function
gtk:list-store-insert-before, Function
gtk:list-store-insert-with-values, Function
gtk:list-store-iter-is-valid, Function
gtk:list-store-move-after, Function
gtk:list-store-move-before, Function
gtk:list-store-new, Function
gtk:list-store-prepend, Function
gtk:list-store-remove, Function
gtk:list-store-reorder, Function
gtk:list-store-set, Function
gtk:list-store-set-value, Function
gtk:list-store-swap, Function
gtk:list-view-enable-rubberband, Accessor
gtk:list-view-factory, Accessor
gtk:list-view-header-factory, Accessor
gtk:list-view-model, Accessor
gtk:list-view-new, Function
gtk:list-view-scroll-to, Function
gtk:list-view-show-separators, Accessor
gtk:list-view-single-click-activate, Accessor
gtk:list-view-tab-behavior, Accessor
gtk:locale-direction, Function
gtk:lock-button-new, Function
gtk:lock-button-permission, Accessor
gtk:lock-button-text-lock, Accessor
gtk:lock-button-text-unlock, Accessor
gtk:lock-button-tooltip-lock, Accessor
gtk:lock-button-tooltip-not-authorized, Accessor
gtk:lock-button-tooltip-unlock, Accessor
gtk:major-version, Function
gtk:map-list-model-has-map, Accessor
gtk:map-list-model-item-type, Accessor
gtk:map-list-model-model, Accessor
gtk:map-list-model-n-items, Accessor
gtk:map-list-model-new, Function
gtk:map-list-model-set-map-func, Function
gtk:media-controls-media-stream, Accessor
gtk:media-controls-new, Function
gtk:media-file-clear, Function
gtk:media-file-file, Accessor
gtk:media-file-new, Function
gtk:media-file-new-for-file, Function
gtk:media-file-new-for-filename, Function
gtk:media-file-new-for-resource, Function
gtk:media-file-set-filename, Function
gtk:media-file-set-resource, Function
gtk:media-stream-duration, Accessor
gtk:media-stream-ended, Accessor
gtk:media-stream-error, Accessor
gtk:media-stream-has-audio, Accessor
gtk:media-stream-has-video, Accessor
gtk:media-stream-is-prepared, Function
gtk:media-stream-is-seekable, Function
gtk:media-stream-is-seeking, Function
gtk:media-stream-loop, Accessor
gtk:media-stream-muted, Accessor
gtk:media-stream-pause, Function
gtk:media-stream-play, Function
gtk:media-stream-playing, Accessor
gtk:media-stream-prepared, Accessor
gtk:media-stream-realize, Function
gtk:media-stream-seek, Function
gtk:media-stream-seek-failed, Function
gtk:media-stream-seek-success, Function
gtk:media-stream-seekable, Accessor
gtk:media-stream-seeking, Accessor
gtk:media-stream-timestamp, Accessor
gtk:media-stream-unrealize, Function
gtk:media-stream-update, Function
gtk:media-stream-volume, Accessor
gtk:menu-button-active, Accessor
gtk:menu-button-always-show-arrow, Accessor
gtk:menu-button-can-shrink, Accessor
gtk:menu-button-child, Accessor
gtk:menu-button-direction, Accessor
gtk:menu-button-has-frame, Accessor
gtk:menu-button-icon-name, Accessor
gtk:menu-button-label, Accessor
gtk:menu-button-menu-model, Accessor
gtk:menu-button-new, Function
gtk:menu-button-popdown, Function
gtk:menu-button-popover, Accessor
gtk:menu-button-popup, Function
gtk:menu-button-primary, Accessor
gtk:menu-button-set-create-popup-func, Function
gtk:menu-button-use-underline, Accessor
gtk:message-dialog-format-secondary-markup, Function
gtk:message-dialog-format-secondary-text, Function
gtk:message-dialog-message-area, Accessor
gtk:message-dialog-message-type, Accessor
gtk:message-dialog-new, Function
gtk:message-dialog-new-with-markup, Function
gtk:message-dialog-secondary-text, Accessor
gtk:message-dialog-secondary-use-markup, Accessor
gtk:message-dialog-set-markup, Function
gtk:message-dialog-text, Accessor
gtk:message-dialog-use-markup, Accessor
gtk:micro-version, Function
gtk:minor-version, Function
gtk:mnemonic-action-get, Function
gtk:mnemonic-trigger-keyval, Accessor
gtk:mnemonic-trigger-new, Function
gtk:multi-filter-append, Function
gtk:multi-filter-item-type, Accessor
gtk:multi-filter-n-items, Accessor
gtk:multi-filter-remove, Function
gtk:multi-selection-item-type, Accessor
gtk:multi-selection-model, Accessor
gtk:multi-selection-n-items, Accessor
gtk:multi-selection-new, Function
gtk:multi-sorter-append, Function
gtk:multi-sorter-item-type, Accessor
gtk:multi-sorter-n-items, Accessor
gtk:multi-sorter-new, Function
gtk:multi-sorter-remove, Function
gtk:named-action-action-name, Accessor
gtk:named-action-new, Function
gtk:native-dialog-destroy, Function
gtk:native-dialog-hide, Function
gtk:native-dialog-modal, Accessor
gtk:native-dialog-show, Function
gtk:native-dialog-title, Accessor
gtk:native-dialog-transient-for, Accessor
gtk:native-dialog-visible, Accessor
gtk:native-for-surface, Function
gtk:native-realize, Function
gtk:native-renderer, Function
gtk:native-surface, Function
gtk:native-surface-transform, Function
gtk:native-unrealize, Function
gtk:never-trigger-get, Function
gtk:no-selection-item-type, Accessor
gtk:no-selection-model, Accessor
gtk:no-selection-n-items, Accessor
gtk:no-selection-new, Function
gtk:notebook-action-widget, Function
gtk:notebook-add-page, Function
gtk:notebook-current-page, Function
gtk:notebook-detach-tab, Function
gtk:notebook-enable-popup, Accessor
gtk:notebook-group-name, Accessor
gtk:notebook-menu-label, Function
gtk:notebook-menu-label-text, Function
gtk:notebook-n-pages, Function
gtk:notebook-new, Function
gtk:notebook-next-page, Function
gtk:notebook-nth-page, Function
gtk:notebook-page, Accessor
gtk:notebook-page-child, Accessor
gtk:notebook-page-detachable, Accessor
gtk:notebook-page-menu, Accessor
gtk:notebook-page-menu-label, Accessor
gtk:notebook-page-num, Function
gtk:notebook-page-position, Accessor
gtk:notebook-page-reorderable, Accessor
gtk:notebook-page-tab, Accessor
gtk:notebook-page-tab-expand, Accessor
gtk:notebook-page-tab-fill, Accessor
gtk:notebook-page-tab-label, Accessor
gtk:notebook-pages, Accessor
gtk:notebook-popup-disable, Function
gtk:notebook-popup-enable, Function
gtk:notebook-prev-page, Function
gtk:notebook-remove-page, Function
gtk:notebook-reorder-child, Function
gtk:notebook-scrollable, Accessor
gtk:notebook-show-border, Accessor
gtk:notebook-show-tabs, Accessor
gtk:notebook-tab-detachable, Function
gtk:notebook-tab-label, Function
gtk:notebook-tab-label-text, Function
gtk:notebook-tab-pos, Accessor
gtk:notebook-tab-reorderable, Function
gtk:nothing-action-get, Function
gtk:numeric-sorter-expression, Accessor
gtk:numeric-sorter-new, Function
gtk:numeric-sorter-sort-order, Accessor
gtk:object-expression-new, Function
gtk:object-expression-object, Function
gtk:ordering-from-cmpfunc, Function
gtk:orientable-orientation, Accessor
gtk:overlay-add-overlay, Function
gtk:overlay-child, Accessor
gtk:overlay-clip-overlay, Function
gtk:overlay-layout-child-clip-overlay, Accessor
gtk:overlay-layout-child-measure, Accessor
gtk:overlay-layout-new, Function
gtk:overlay-measure-overlay, Function
gtk:overlay-new, Function
gtk:overlay-remove-overlay, Function
gtk:pad-controller-action-group, Accessor
gtk:pad-controller-new, Function
gtk:pad-controller-pad, Accessor
gtk:pad-controller-set-action, Function
gtk:pad-controller-set-action-entries, Function
gtk:page-setup-bottom-margin, Function
gtk:page-setup-copy, Function
gtk:page-setup-left-margin, Function
gtk:page-setup-load-file, Function
gtk:page-setup-load-key-file, Function
gtk:page-setup-new, Function
gtk:page-setup-new-from-file, Function
gtk:page-setup-new-from-gvariant, Function
gtk:page-setup-new-from-key-file, Function
gtk:page-setup-orientation, Function
gtk:page-setup-page-height, Function
gtk:page-setup-page-width, Function
gtk:page-setup-paper-height, Function
gtk:page-setup-paper-size, Function
gtk:page-setup-paper-width, Function
gtk:page-setup-right-margin, Function
gtk:page-setup-set-paper-size-and-default-margins, Function
gtk:page-setup-to-file, Function
gtk:page-setup-to-gvariant, Function
gtk:page-setup-to-key-file, Function
gtk:page-setup-top-margin, Function
gtk:page-setup-unix-dialog-new, Function
gtk:page-setup-unix-dialog-page-setup, Function
gtk:page-setup-unix-dialog-print-settings, Function
gtk:paned-end-child, Accessor
gtk:paned-max-position, Accessor
gtk:paned-min-position, Accessor
gtk:paned-new, Function
gtk:paned-position, Accessor
gtk:paned-position-set, Accessor
gtk:paned-resize-end-child, Accessor
gtk:paned-resize-start-child, Accessor
gtk:paned-shrink-end-child, Accessor
gtk:paned-shrink-start-child, Accessor
gtk:paned-start-child, Accessor
gtk:paned-wide-handle, Accessor
gtk:paper-size-copy, Function
gtk:paper-size-default, Function
gtk:paper-size-default-bottom-margin, Function
gtk:paper-size-default-left-margin, Function
gtk:paper-size-default-right-margin, Function
gtk:paper-size-default-top-margin, Function
gtk:paper-size-display-name, Function
gtk:paper-size-height, Function
gtk:paper-size-is-custom, Function
gtk:paper-size-is-equal, Function
gtk:paper-size-is-ipp, Function
gtk:paper-size-name, Function
gtk:paper-size-new, Function
gtk:paper-size-new-custom, Function
gtk:paper-size-new-from-gvariant, Function
gtk:paper-size-new-from-ipp, Function
gtk:paper-size-new-from-key-file, Function
gtk:paper-size-new-from-ppd, Function
gtk:paper-size-paper-sizes, Function
gtk:paper-size-ppd-name, Function
gtk:paper-size-set-size, Function
gtk:paper-size-to-gvariant, Function
gtk:paper-size-to-key-file, Function
gtk:paper-size-width, Function
gtk:password-entry-activates-default, Accessor
gtk:password-entry-buffer-new, Function
gtk:password-entry-extra-menu, Accessor
gtk:password-entry-new, Function
gtk:password-entry-placeholder-text, Accessor
gtk:password-entry-show-peek-icon, Accessor
gtk:picture-alternative-text, Accessor
gtk:picture-can-shrink, Accessor
gtk:picture-content-fit, Accessor
gtk:picture-file, Accessor
gtk:picture-keep-aspect-ratio, Accessor
gtk:picture-new, Function
gtk:picture-new-for-file, Function
gtk:picture-new-for-filename, Function
gtk:picture-new-for-paintable, Function
gtk:picture-new-for-pixbuf, Function
gtk:picture-new-for-resource, Function
gtk:picture-paintable, Accessor
gtk:picture-set-filename, Function
gtk:picture-set-pixbuf, Function
gtk:picture-set-resource, Function
gtk:popover-autohide, Accessor
gtk:popover-cascade-popdown, Accessor
gtk:popover-child, Accessor
gtk:popover-default-widget, Accessor
gtk:popover-has-arrow, Accessor
gtk:popover-menu-add-child, Function
gtk:popover-menu-bar-add-child, Function
gtk:popover-menu-bar-menu-model, Accessor
gtk:popover-menu-bar-new-from-model, Function
gtk:popover-menu-bar-remove-child, Function
gtk:popover-menu-flags, Accessor
gtk:popover-menu-menu-model, Accessor
gtk:popover-menu-new-from-model, Function
gtk:popover-menu-new-from-model-full, Function
gtk:popover-menu-remove-child, Function
gtk:popover-menu-visible-submenu, Accessor
gtk:popover-mnemonics-visible, Accessor
gtk:popover-new, Function
gtk:popover-offset, Function
gtk:popover-pointing-to, Accessor
gtk:popover-popdown, Function
gtk:popover-popup, Function
gtk:popover-position, Accessor
gtk:popover-present, Function
gtk:print-context-cairo-context, Function
gtk:print-context-create-pango-context, Function
gtk:print-context-create-pango-layout, Function
gtk:print-context-dpi-x, Function
gtk:print-context-dpi-y, Function
gtk:print-context-hard-margins, Function
gtk:print-context-height, Function
gtk:print-context-page-setup, Function
gtk:print-context-pango-fontmap, Function
gtk:print-context-set-cairo-context, Function
gtk:print-context-width, Function
gtk:print-dialog-accept-label, Accessor
gtk:print-dialog-modal, Accessor
gtk:print-dialog-new, Function
gtk:print-dialog-page-setup, Accessor
gtk:print-dialog-print-file, Function
gtk:print-dialog-print-file-finish, Function
gtk:print-dialog-print-settings, Accessor
gtk:print-dialog-setup, Function
gtk:print-dialog-setup-finish, Function
gtk:print-dialog-title, Accessor
gtk:print-job-collate, Function
gtk:print-job-n-up, Function
gtk:print-job-n-up-layout, Function
gtk:print-job-new, Function
gtk:print-job-num-copies, Function
gtk:print-job-page-ranges, Function
gtk:print-job-page-set, Function
gtk:print-job-page-setup, Accessor
gtk:print-job-pages, Function
gtk:print-job-printer, Accessor
gtk:print-job-reverse, Function
gtk:print-job-rotate, Function
gtk:print-job-scale, Function
gtk:print-job-send, Function
gtk:print-job-set-source-file, Function
gtk:print-job-settings, Accessor
gtk:print-job-status, Function
gtk:print-job-surface, Function
gtk:print-job-title, Accessor
gtk:print-job-track-print-status, Accessor
gtk:print-operation-allow-async, Accessor
gtk:print-operation-cancel, Function
gtk:print-operation-current-page, Accessor
gtk:print-operation-custom-tab-label, Accessor
gtk:print-operation-default-page-setup, Accessor
gtk:print-operation-draw-page-finish, Function
gtk:print-operation-embed-page-setup, Accessor
gtk:print-operation-export-filename, Accessor
gtk:print-operation-has-selection, Accessor
gtk:print-operation-is-finished, Function
gtk:print-operation-job-name, Accessor
gtk:print-operation-n-pages, Accessor
gtk:print-operation-n-pages-to-print, Accessor
gtk:print-operation-new, Function
gtk:print-operation-preview-end-preview, Function
gtk:print-operation-preview-is-selected, Function
gtk:print-operation-preview-render-page, Function
gtk:print-operation-print-settings, Accessor
gtk:print-operation-run, Function
gtk:print-operation-set-defer-drawing, Function
gtk:print-operation-show-progress, Accessor
gtk:print-operation-status, Accessor
gtk:print-operation-status-string, Accessor
gtk:print-operation-support-selection, Accessor
gtk:print-operation-track-print-status, Accessor
gtk:print-operation-unit, Accessor
gtk:print-operation-use-full-page, Accessor
gtk:print-run-page-setup-dialog, Function
gtk:print-run-page-setup-dialog-async, Function
gtk:print-settings-bool, Function
gtk:print-settings-collate, Function
gtk:print-settings-copy, Function
gtk:print-settings-default-source, Function
gtk:print-settings-dither, Function
gtk:print-settings-double, Function
gtk:print-settings-double-with-default, Function
gtk:print-settings-duplex, Function
gtk:print-settings-finishings, Function
gtk:print-settings-foreach, Function
gtk:print-settings-get, Function
gtk:print-settings-has-key, Function
gtk:print-settings-int, Function
gtk:print-settings-int-with-default, Function
gtk:print-settings-length, Function
gtk:print-settings-load-file, Function
gtk:print-settings-load-key-file, Function
gtk:print-settings-media-type, Function
gtk:print-settings-n-copies, Function
gtk:print-settings-new, Function
gtk:print-settings-new-from-file, Function
gtk:print-settings-new-from-gvariant, Function
gtk:print-settings-new-from-key-file, Function
gtk:print-settings-number-up, Function
gtk:print-settings-number-up-layout, Function
gtk:print-settings-orientation, Function
gtk:print-settings-output-bin, Function
gtk:print-settings-page-ranges, Function
gtk:print-settings-page-set, Function
gtk:print-settings-paper-height, Function
gtk:print-settings-paper-size, Function
gtk:print-settings-paper-width, Function
gtk:print-settings-print-pages, Function
gtk:print-settings-printer, Function
gtk:print-settings-printer-lpi, Function
gtk:print-settings-quality, Function
gtk:print-settings-resolution, Function
gtk:print-settings-resolution-x, Function
gtk:print-settings-resolution-y, Function
gtk:print-settings-reverse, Function
gtk:print-settings-scale, Function
gtk:print-settings-set, Function
gtk:print-settings-to-file, Function
gtk:print-settings-to-gvariant, Function
gtk:print-settings-to-key-file, Function
gtk:print-settings-unset, Function
gtk:print-settings-use-color, Function
gtk:print-setup-page-setup, Function
gtk:print-setup-print-settings, Function
gtk:print-unix-dialog-add-custom-tab, Function
gtk:print-unix-dialog-current-page, Accessor
gtk:print-unix-dialog-embed-page-setup, Accessor
gtk:print-unix-dialog-has-selection, Accessor
gtk:print-unix-dialog-manual-capabilities, Accessor
gtk:print-unix-dialog-new, Function
gtk:print-unix-dialog-page-setup, Accessor
gtk:print-unix-dialog-page-setup-set, Function
gtk:print-unix-dialog-print-settings, Accessor
gtk:print-unix-dialog-selected-printer, Accessor
gtk:print-unix-dialog-settings, Function
gtk:print-unix-dialog-support-selection, Accessor
gtk:printer-accepting-jobs, Accessor
gtk:printer-accepts-pdf, Accessor
gtk:printer-accepts-ps, Accessor
gtk:printer-backend, Accessor
gtk:printer-capabilities, Function
gtk:printer-compare, Function
gtk:printer-default-page-size, Function
gtk:printer-description, Function
gtk:printer-hard-margins, Function
gtk:printer-hard-margins-for-paper-size, Function
gtk:printer-has-details, Function
gtk:printer-icon-name, Accessor
gtk:printer-is-accepting-jobs, Function
gtk:printer-is-active, Function
gtk:printer-is-default, Function
gtk:printer-is-paused, Function
gtk:printer-is-virtual, Accessor
gtk:printer-job-count, Accessor
gtk:printer-list-papers, Function
gtk:printer-location, Accessor
gtk:printer-name, Accessor
gtk:printer-new, Function
gtk:printer-paused, Accessor
gtk:printer-request-details, Function
gtk:printer-state-message, Accessor
gtk:progress-bar-ellipsize, Accessor
gtk:progress-bar-fraction, Accessor
gtk:progress-bar-inverted, Accessor
gtk:progress-bar-new, Function
gtk:progress-bar-pulse, Function
gtk:progress-bar-pulse-step, Accessor
gtk:progress-bar-show-text, Accessor
gtk:progress-bar-text, Accessor
gtk:property-expression-expression, Function
gtk:property-expression-new, Function
gtk:property-expression-new-for-pspec, Function
gtk:property-expression-pspec, Function
gtk:range-adjustment, Accessor
gtk:range-fill-level, Accessor
gtk:range-flippable, Function
gtk:range-inverted, Accessor
gtk:range-range-rect, Function
gtk:range-restrict-to-fill-level, Accessor
gtk:range-round-digits, Accessor
gtk:range-set-increments, Function
gtk:range-set-range, Function
gtk:range-show-fill-level, Accessor
gtk:range-slider-range, Function
gtk:range-slider-size-fixed, Function
gtk:range-value, Function
gtk:recent-info-added, Function
gtk:recent-info-age, Function
gtk:recent-info-application-info, Function
gtk:recent-info-applications, Function
gtk:recent-info-create-app-info, Function
gtk:recent-info-description, Function
gtk:recent-info-display-name, Function
gtk:recent-info-exists, Function
gtk:recent-info-gicon, Function
gtk:recent-info-groups, Function
gtk:recent-info-has-application, Function
gtk:recent-info-has-group, Function
gtk:recent-info-is-local, Function
gtk:recent-info-last-application, Function
gtk:recent-info-match, Function
gtk:recent-info-mime-type, Function
gtk:recent-info-modified, Function
gtk:recent-info-private-hint, Function
gtk:recent-info-short-name, Function
gtk:recent-info-uri, Function
gtk:recent-info-uri-display, Function
gtk:recent-info-visited, Function
gtk:recent-manager-add-item, Function
gtk:recent-manager-default, Function
gtk:recent-manager-filename, Accessor
gtk:recent-manager-has-item, Function
gtk:recent-manager-items, Function
gtk:recent-manager-lookup-item, Function
gtk:recent-manager-move-item, Function
gtk:recent-manager-new, Function
gtk:recent-manager-purge-items, Function
gtk:recent-manager-remove-item, Function
gtk:recent-manager-size, Accessor
gtk:render-activity, Function
gtk:render-arrow, Function
gtk:render-background, Function
gtk:render-check, Function
gtk:render-expander, Function
gtk:render-focus, Function
gtk:render-frame, Function
gtk:render-handle, Function
gtk:render-icon, Function
gtk:render-layout, Function
gtk:render-line, Function
gtk:render-option, Function
gtk:requisition-copy, Function
gtk:requisition-height, Accessor
gtk:requisition-new, Function
gtk:requisition-width, Accessor
gtk:response-type-keyword, Function
gtk:revealer-child, Accessor
gtk:revealer-child-revealed, Accessor
gtk:revealer-new, Function
gtk:revealer-reveal-child, Accessor
gtk:revealer-transition-duration, Accessor
gtk:revealer-transition-type, Accessor
gtk:rgb-to-hsv, Function
gtk:root-display, Function
gtk:root-focus, Function
gtk:scale-add-mark, Function
gtk:scale-button-active, Accessor
gtk:scale-button-adjustment, Accessor
gtk:scale-button-has-frame, Accessor
gtk:scale-button-icons, Accessor
gtk:scale-button-minus-button, Function
gtk:scale-button-new, Function
gtk:scale-button-plus-button, Function
gtk:scale-button-popup, Function
gtk:scale-button-value, Accessor
gtk:scale-clear-marks, Function
gtk:scale-digits, Accessor
gtk:scale-draw-value, Accessor
gtk:scale-has-origin, Accessor
gtk:scale-layout, Function
gtk:scale-layout-offsets, Function
gtk:scale-new, Function
gtk:scale-new-with-range, Function
gtk:scale-set-format-value-func, Function
gtk:scale-value-pos, Accessor
gtk:scroll-info-enable-horizontal, Function
gtk:scroll-info-enable-vertical, Function
gtk:scroll-info-new, Function
gtk:scrollable-border, Function
gtk:scrollable-hadjustment, Accessor
gtk:scrollable-hscroll-policy, Accessor
gtk:scrollable-vadjustment, Accessor
gtk:scrollable-vscroll-policy, Accessor
gtk:scrollbar-adjustment, Accessor
gtk:scrollbar-new, Function
gtk:scrolled-window-child, Accessor
gtk:scrolled-window-hadjustment, Accessor
gtk:scrolled-window-has-frame, Accessor
gtk:scrolled-window-hscrollbar, Function
gtk:scrolled-window-hscrollbar-policy, Accessor
gtk:scrolled-window-kinetic-scrolling, Accessor
gtk:scrolled-window-max-content-height, Accessor
gtk:scrolled-window-max-content-width, Accessor
gtk:scrolled-window-min-content-height, Accessor
gtk:scrolled-window-min-content-width, Accessor
gtk:scrolled-window-new, Function
gtk:scrolled-window-overlay-scrolling, Accessor
gtk:scrolled-window-placement, Function
gtk:scrolled-window-policy, Function
gtk:scrolled-window-propagate-natural-height, Accessor
gtk:scrolled-window-propagate-natural-width, Accessor
gtk:scrolled-window-unset-placement, Function
gtk:scrolled-window-vadjustment, Accessor
gtk:scrolled-window-vscrollbar, Function
gtk:scrolled-window-vscrollbar-policy, Accessor
gtk:scrolled-window-window-placement, Accessor
gtk:search-bar-child, Accessor
gtk:search-bar-connect-entry, Function
gtk:search-bar-key-capture-widget, Accessor
gtk:search-bar-new, Function
gtk:search-bar-search-mode-enabled, Accessor
gtk:search-bar-show-close-button, Accessor
gtk:search-entry-activates-default, Accessor
gtk:search-entry-input-hints, Accessor
gtk:search-entry-input-purpose, Accessor
gtk:search-entry-key-capture-widget, Function
gtk:search-entry-new, Function
gtk:search-entry-placeholder-text, Accessor
gtk:search-entry-search-delay, Accessor
gtk:section-model-section, Function
gtk:section-model-sections-changed, Function
gtk:selection-filter-model-item-type, Accessor
gtk:selection-filter-model-model, Accessor
gtk:selection-filter-model-n-items, Accessor
gtk:selection-filter-model-new, Function
gtk:selection-model-is-selected, Function
gtk:selection-model-select-all, Function
gtk:selection-model-select-item, Function
gtk:selection-model-select-range, Function
gtk:selection-model-selection, Function
gtk:selection-model-selection-changed, Function
gtk:selection-model-selection-in-range, Function
gtk:selection-model-unselect-all, Function
gtk:selection-model-unselect-item, Function
gtk:selection-model-unselect-range, Function
gtk:separator-new, Function
gtk:settings-default, Function
gtk:settings-for-display, Function
gtk:settings-gtk-alternative-button-order, Accessor
gtk:settings-gtk-alternative-sort-arrows, Accessor
gtk:settings-gtk-application-prefer-dark-theme, Accessor
gtk:settings-gtk-cursor-aspect-ratio, Accessor
gtk:settings-gtk-cursor-blink, Accessor
gtk:settings-gtk-cursor-blink-time, Accessor
gtk:settings-gtk-cursor-blink-timeout, Accessor
gtk:settings-gtk-cursor-theme-name, Accessor
gtk:settings-gtk-cursor-theme-size, Accessor
gtk:settings-gtk-decoration-layout, Accessor
gtk:settings-gtk-dialogs-use-header, Accessor
gtk:settings-gtk-dnd-drag-threshold, Accessor
gtk:settings-gtk-double-click-distance, Accessor
gtk:settings-gtk-double-click-time, Accessor
gtk:settings-gtk-enable-accels, Accessor
gtk:settings-gtk-enable-animations, Accessor
gtk:settings-gtk-enable-event-sounds, Accessor
gtk:settings-gtk-enable-input-feedback-sounds, Accessor
gtk:settings-gtk-enable-primary-paste, Accessor
gtk:settings-gtk-entry-password-hint-timeout, Accessor
gtk:settings-gtk-entry-select-on-focus, Accessor
gtk:settings-gtk-error-bell, Accessor
gtk:settings-gtk-font-name, Accessor
gtk:settings-gtk-font-rendering, Accessor
gtk:settings-gtk-fontconfig-timestamp, Accessor
gtk:settings-gtk-hint-font-metrics, Accessor
gtk:settings-gtk-icon-theme-name, Accessor
gtk:settings-gtk-im-module, Accessor
gtk:settings-gtk-keynav-use-caret, Accessor
gtk:settings-gtk-label-select-on-focus, Accessor
gtk:settings-gtk-long-press-time, Accessor
gtk:settings-gtk-overlay-scrolling, Accessor
gtk:settings-gtk-primary-button-warps-slider, Accessor
gtk:settings-gtk-print-backends, Accessor
gtk:settings-gtk-print-preview-command, Accessor
gtk:settings-gtk-recent-files-enabled, Accessor
gtk:settings-gtk-recent-files-max-age, Accessor
gtk:settings-gtk-shell-shows-app-menu, Accessor
gtk:settings-gtk-shell-shows-desktop, Accessor
gtk:settings-gtk-shell-shows-menubar, Accessor
gtk:settings-gtk-show-status-shapes, Accessor
gtk:settings-gtk-sound-theme-name, Accessor
gtk:settings-gtk-split-cursor, Accessor
gtk:settings-gtk-theme-name, Accessor
gtk:settings-gtk-titlebar-double-click, Accessor
gtk:settings-gtk-titlebar-middle-click, Accessor
gtk:settings-gtk-titlebar-right-click, Accessor
gtk:settings-gtk-xft-antialias, Accessor
gtk:settings-gtk-xft-dpi, Accessor
gtk:settings-gtk-xft-hinting, Accessor
gtk:settings-gtk-xft-hintstyle, Accessor
gtk:settings-gtk-xft-rgba, Accessor
gtk:settings-reset-property, Function
gtk:shortcut-action, Accessor
gtk:shortcut-action-activate, Function
gtk:shortcut-action-parse-string, Function
gtk:shortcut-action-to-string, Function
gtk:shortcut-arguments, Accessor
gtk:shortcut-controller-add-shortcut, Function
gtk:shortcut-controller-item-type, Accessor
gtk:shortcut-controller-mnemonic-modifiers, Accessor
gtk:shortcut-controller-model, Accessor
gtk:shortcut-controller-n-items, Accessor
gtk:shortcut-controller-new, Function
gtk:shortcut-controller-new-for-model, Function
gtk:shortcut-controller-remove-shortcut, Function
gtk:shortcut-controller-scope, Accessor
gtk:shortcut-label-accelerator, Accessor
gtk:shortcut-label-disabled-text, Accessor
gtk:shortcut-label-new, Function
gtk:shortcut-manager-add-controller, Function
gtk:shortcut-manager-remove-controller, Function
gtk:shortcut-new, Function
gtk:shortcut-trigger, Accessor
gtk:shortcut-trigger-parse-string, Function
gtk:shortcut-trigger-to-label, Function
gtk:shortcut-trigger-to-string, Function
gtk:shortcut-trigger-trigger, Function
gtk:shortcuts-group-accel-size-group, Accessor
gtk:shortcuts-group-add-shortcut, Function
gtk:shortcuts-group-height, Accessor
gtk:shortcuts-group-title, Accessor
gtk:shortcuts-group-title-size-group, Accessor
gtk:shortcuts-group-view, Accessor
gtk:shortcuts-section-add-group, Function
gtk:shortcuts-section-max-height, Accessor
gtk:shortcuts-section-section-name, Accessor
gtk:shortcuts-section-title, Accessor
gtk:shortcuts-section-view-name, Accessor
gtk:shortcuts-shortcut-accel-size-group, Accessor
gtk:shortcuts-shortcut-accelerator, Accessor
gtk:shortcuts-shortcut-action-name, Accessor
gtk:shortcuts-shortcut-direction, Accessor
gtk:shortcuts-shortcut-icon, Accessor
gtk:shortcuts-shortcut-icon-set, Accessor
gtk:shortcuts-shortcut-shortcut-type, Accessor
gtk:shortcuts-shortcut-subtitle, Accessor
gtk:shortcuts-shortcut-subtitle-set, Accessor
gtk:shortcuts-shortcut-title, Accessor
gtk:shortcuts-shortcut-title-size-group, Accessor
gtk:shortcuts-window-add-section, Function
gtk:shortcuts-window-section-name, Accessor
gtk:shortcuts-window-view-name, Accessor
gtk:show-about-dialog, Function
gtk:signal-action-new, Function
gtk:signal-action-signal-name, Accessor
gtk:signal-list-item-factory-new, Function
gtk:single-selection-autoselect, Accessor
gtk:single-selection-can-unselect, Accessor
gtk:single-selection-item-type, Accessor
gtk:single-selection-model, Accessor
gtk:single-selection-n-items, Accessor
gtk:single-selection-new, Function
gtk:single-selection-selected, Accessor
gtk:single-selection-selected-item, Accessor
gtk:size-group-add-widget, Function
gtk:size-group-mode, Accessor
gtk:size-group-new, Function
gtk:size-group-remove-widget, Function
gtk:size-group-widgets, Function
gtk:slice-list-model-item-type, Accessor
gtk:slice-list-model-model, Accessor
gtk:slice-list-model-n-items, Accessor
gtk:slice-list-model-new, Function
gtk:slice-list-model-offset, Accessor
gtk:slice-list-model-size, Accessor
gtk:snapshot-append-border, Function
gtk:snapshot-append-cairo, Function
gtk:snapshot-append-color, Function
gtk:snapshot-append-conic-gradient, Function
gtk:snapshot-append-fill, Function
gtk:snapshot-append-inset-shadow, Function
gtk:snapshot-append-layout, Function
gtk:snapshot-append-linear-gradient, Function
gtk:snapshot-append-node, Function
gtk:snapshot-append-outset-shadow, Function
gtk:snapshot-append-radial-gradient, Function
gtk:snapshot-append-repeating-linear-gradient, Function
gtk:snapshot-append-repeating-radial-gradient, Function
gtk:snapshot-append-scaled-texture, Function
gtk:snapshot-append-stroke, Function
gtk:snapshot-append-texture, Function
gtk:snapshot-new, Function
gtk:snapshot-perspective, Function
gtk:snapshot-pop, Function
gtk:snapshot-push-blend, Function
gtk:snapshot-push-blur, Function
gtk:snapshot-push-clip, Function
gtk:snapshot-push-color-matrix, Function
gtk:snapshot-push-cross-fade, Function
gtk:snapshot-push-fill, Function
gtk:snapshot-push-mask, Function
gtk:snapshot-push-opacity, Function
gtk:snapshot-push-repeat, Function
gtk:snapshot-push-rounded-clip, Function
gtk:snapshot-push-shadow, Function
gtk:snapshot-push-stroke, Function
gtk:snapshot-restore, Function
gtk:snapshot-rotate, Function
gtk:snapshot-rotate-3d, Function
gtk:snapshot-save, Function
gtk:snapshot-scale, Function
gtk:snapshot-scale-3d, Function
gtk:snapshot-to-node, Function
gtk:snapshot-to-paintable, Function
gtk:snapshot-transform, Function
gtk:snapshot-transform-matrix, Function
gtk:snapshot-translate, Function
gtk:snapshot-translate-3d, Function
gtk:sort-list-model-incremental, Accessor
gtk:sort-list-model-item-type, Accessor
gtk:sort-list-model-model, Accessor
gtk:sort-list-model-n-items, Accessor
gtk:sort-list-model-new, Function
gtk:sort-list-model-pending, Accessor
gtk:sort-list-model-section-sorter, Accessor
gtk:sort-list-model-sorter, Accessor
gtk:sorter-changed, Function
gtk:sorter-compare, Function
gtk:sorter-order, Function
gtk:spin-button-activates-default, Accessor
gtk:spin-button-adjustment, Accessor
gtk:spin-button-climb-rate, Accessor
gtk:spin-button-configure, Function
gtk:spin-button-digits, Accessor
gtk:spin-button-increments, Function
gtk:spin-button-new, Function
gtk:spin-button-new-with-range, Function
gtk:spin-button-numeric, Accessor
gtk:spin-button-range, Function
gtk:spin-button-snap-to-ticks, Accessor
gtk:spin-button-spin, Function
gtk:spin-button-update, Function
gtk:spin-button-update-policy, Accessor
gtk:spin-button-value, Accessor
gtk:spin-button-value-as-int, Function
gtk:spin-button-wrap, Accessor
gtk:spinner-new, Function
gtk:spinner-spinning, Accessor
gtk:spinner-start, Function
gtk:spinner-stop, Function
gtk:stack-add-named, Function
gtk:stack-add-titled, Function
gtk:stack-child-by-name, Function
gtk:stack-hhomogeneous, Accessor
gtk:stack-interpolate-size, Accessor
gtk:stack-new, Function
gtk:stack-page, Function
gtk:stack-page-child, Accessor
gtk:stack-page-icon-name, Accessor
gtk:stack-page-name, Accessor
gtk:stack-page-needs-attention, Accessor
gtk:stack-page-title, Accessor
gtk:stack-page-use-underline, Accessor
gtk:stack-page-visible, Accessor
gtk:stack-pages, Accessor
gtk:stack-remove, Function
gtk:stack-set-visible-child-full, Function
gtk:stack-sidebar-new, Function
gtk:stack-sidebar-stack, Accessor
gtk:stack-switcher-new, Function
gtk:stack-switcher-stack, Accessor
gtk:stack-transition-duration, Accessor
gtk:stack-transition-running, Accessor
gtk:stack-transition-type, Accessor
gtk:stack-vhomogeneous, Accessor
gtk:stack-visible-child, Accessor
gtk:stack-visible-child-name, Accessor
gtk:statusbar-context-id, Function
gtk:statusbar-new, Function
gtk:statusbar-pop, Function
gtk:statusbar-push, Function
gtk:statusbar-remove, Function
gtk:statusbar-remove-all, Function
gtk:string-filter-expression, Accessor
gtk:string-filter-ignore-case, Accessor
gtk:string-filter-match-mode, Accessor
gtk:string-filter-new, Function
gtk:string-filter-search, Accessor
gtk:string-list-append, Function
gtk:string-list-item-type, Accessor
gtk:string-list-n-items, Accessor
gtk:string-list-new, Function
gtk:string-list-remove, Function
gtk:string-list-splice, Function
gtk:string-list-string, Function
gtk:string-object-new, Function
gtk:string-object-string, Accessor
gtk:string-sorter-collation, Accessor
gtk:string-sorter-expression, Accessor
gtk:string-sorter-ignore-case, Accessor
gtk:string-sorter-new, Function
gtk:style-context-add-class, Function
gtk:style-context-add-provider, Function
gtk:style-context-add-provider-for-display, Function
gtk:style-context-border, Function
gtk:style-context-color, Function
gtk:style-context-display, Accessor
gtk:style-context-has-class, Function
gtk:style-context-lookup-color, Function
gtk:style-context-margin, Function
gtk:style-context-padding, Function
gtk:style-context-remove-class, Function
gtk:style-context-remove-provider, Function
gtk:style-context-remove-provider-for-display, Function
gtk:style-context-restore, Function
gtk:style-context-save, Function
gtk:style-context-scale, Function
gtk:style-context-state, Function
gtk:style-context-to-string, Function
gtk:switch-active, Accessor
gtk:switch-new, Function
gtk:switch-state, Accessor
gtk:text-activates-default, Accessor
gtk:text-attributes, Accessor
gtk:text-buffer, Accessor
gtk:text-buffer-add-commit-notify, Function
gtk:text-buffer-add-mark, Function
gtk:text-buffer-add-selection-clipboard, Function
gtk:text-buffer-apply-tag, Function
gtk:text-buffer-backspace, Function
gtk:text-buffer-begin-irreversible-action, Function
gtk:text-buffer-begin-user-action, Function
gtk:text-buffer-bounds, Function
gtk:text-buffer-can-redo, Accessor
gtk:text-buffer-can-undo, Accessor
gtk:text-buffer-char-count, Function
gtk:text-buffer-copy-clipboard, Function
gtk:text-buffer-create-child-anchor, Function
gtk:text-buffer-create-mark, Function
gtk:text-buffer-create-tag, Function
gtk:text-buffer-cursor-position, Accessor
gtk:text-buffer-cut-clipboard, Function
gtk:text-buffer-delete, Function
gtk:text-buffer-delete-mark, Function
gtk:text-buffer-delete-selection, Function
gtk:text-buffer-enable-undo, Accessor
gtk:text-buffer-end-irreversible-action, Function
gtk:text-buffer-end-iter, Function
gtk:text-buffer-end-user-action, Function
gtk:text-buffer-get-insert, Function
gtk:text-buffer-get-slice, Function
gtk:text-buffer-get-text, Function
gtk:text-buffer-has-selection, Accessor
gtk:text-buffer-insert, Function
gtk:text-buffer-insert-child-anchor, Function
gtk:text-buffer-insert-markup, Function
gtk:text-buffer-insert-paintable, Function
gtk:text-buffer-insert-range, Function
gtk:text-buffer-insert-with-tags, Function
gtk:text-buffer-iter-at-child-anchor, Function
gtk:text-buffer-iter-at-line, Function
gtk:text-buffer-iter-at-line-index, Function
gtk:text-buffer-iter-at-line-offset, Function
gtk:text-buffer-iter-at-mark, Function
gtk:text-buffer-iter-at-offset, Function
gtk:text-buffer-line-count, Function
gtk:text-buffer-load-file, Function
gtk:text-buffer-mark, Function
gtk:text-buffer-max-undo-levels, Function
gtk:text-buffer-modified, Function
gtk:text-buffer-move-mark, Function
gtk:text-buffer-new, Function
gtk:text-buffer-paste-clipboard, Function
gtk:text-buffer-place-cursor, Function
gtk:text-buffer-redo, Function
gtk:text-buffer-remove-all-tags, Function
gtk:text-buffer-remove-commit-notify, Function
gtk:text-buffer-remove-selection-clipboard, Function
gtk:text-buffer-remove-tag, Function
gtk:text-buffer-select-range, Function
gtk:text-buffer-selection-bound, Function
gtk:text-buffer-selection-bounds, Function
gtk:text-buffer-selection-content, Function
gtk:text-buffer-start-iter, Function
gtk:text-buffer-tag-table, Accessor
gtk:text-buffer-text, Accessor
gtk:text-buffer-undo, Function
gtk:text-child-anchor-deleted, Function
gtk:text-child-anchor-new, Function
gtk:text-child-anchor-new-with-replacement, Function
gtk:text-child-anchor-widgets, Function
gtk:text-compute-cursor-extents, Function
gtk:text-enable-emoji-completion, Accessor
gtk:text-extra-menu, Accessor
gtk:text-grab-focus-without-selecting, Function
gtk:text-im-module, Accessor
gtk:text-input-hints, Accessor
gtk:text-input-purpose, Accessor
gtk:text-invisible-char, Accessor
gtk:text-invisible-char-set, Accessor
gtk:text-iter-assign, Function
gtk:text-iter-backward-to-tag-toggle, Function
gtk:text-iter-buffer, Function
gtk:text-iter-bytes-in-line, Function
gtk:text-iter-can-insert, Function
gtk:text-iter-char, Function
gtk:text-iter-chars-in-line, Function
gtk:text-iter-child-anchor, Function
gtk:text-iter-compare, Function
gtk:text-iter-copy, Function
gtk:text-iter-editable, Function
gtk:text-iter-ends-line, Function
gtk:text-iter-ends-sentence, Function
gtk:text-iter-ends-tag, Function
gtk:text-iter-ends-word, Function
gtk:text-iter-equal, Function
gtk:text-iter-find-char, Function
gtk:text-iter-forward-to-end, Function
gtk:text-iter-forward-to-line-end, Function
gtk:text-iter-forward-to-tag-toggle, Function
gtk:text-iter-has-tag, Function
gtk:text-iter-in-range, Function
gtk:text-iter-inside-sentence, Function
gtk:text-iter-inside-word, Function
gtk:text-iter-is-cursor-position, Function
gtk:text-iter-is-end, Function
gtk:text-iter-is-start, Function
gtk:text-iter-language, Function
gtk:text-iter-line, Function
gtk:text-iter-line-index, Function
gtk:text-iter-line-offset, Function
gtk:text-iter-marks, Function
gtk:text-iter-move, Function
gtk:text-iter-new, Function
gtk:text-iter-offset, Function
gtk:text-iter-order, Function
gtk:text-iter-paintable, Function
gtk:text-iter-search, Function
gtk:text-iter-slice, Function
gtk:text-iter-starts-line, Function
gtk:text-iter-starts-sentence, Function
gtk:text-iter-starts-tag, Function
gtk:text-iter-starts-word, Function
gtk:text-iter-tags, Function
gtk:text-iter-text, Function
gtk:text-iter-toggled-tags, Function
gtk:text-iter-toggles-tag, Function
gtk:text-mark-buffer, Function
gtk:text-mark-deleted, Function
gtk:text-mark-left-gravity, Accessor
gtk:text-mark-name, Accessor
gtk:text-mark-new, Function
gtk:text-mark-visible, Function
gtk:text-max-length, Accessor
gtk:text-new, Function
gtk:text-new-with-buffer, Function
gtk:text-overwrite-mode, Accessor
gtk:text-placeholder-text, Accessor
gtk:text-propagate-text-width, Accessor
gtk:text-scroll-offset, Accessor
gtk:text-tabs, Accessor
gtk:text-tag-accumulative-margin, Accessor
gtk:text-tag-allow-breaks, Accessor
gtk:text-tag-allow-breaks-set, Accessor
gtk:text-tag-background, Accessor
gtk:text-tag-background-full-height, Accessor
gtk:text-tag-background-full-height-set, Accessor
gtk:text-tag-background-rgba, Accessor
gtk:text-tag-background-set, Accessor
gtk:text-tag-changed, Function
gtk:text-tag-direction, Accessor
gtk:text-tag-editable, Accessor
gtk:text-tag-editable-set, Accessor
gtk:text-tag-fallback, Accessor
gtk:text-tag-fallback-set, Accessor
gtk:text-tag-family, Accessor
gtk:text-tag-family-set, Accessor
gtk:text-tag-font, Accessor
gtk:text-tag-font-desc, Accessor
gtk:text-tag-font-features, Accessor
gtk:text-tag-font-features-set, Accessor
gtk:text-tag-foreground, Accessor
gtk:text-tag-foreground-rgba, Accessor
gtk:text-tag-foreground-set, Accessor
gtk:text-tag-indent, Accessor
gtk:text-tag-indent-set, Accessor
gtk:text-tag-insert-hyphens, Accessor
gtk:text-tag-insert-hyphens-set, Accessor
gtk:text-tag-invisible, Accessor
gtk:text-tag-invisible-set, Accessor
gtk:text-tag-justification, Accessor
gtk:text-tag-justification-set, Accessor
gtk:text-tag-language, Accessor
gtk:text-tag-language-set, Accessor
gtk:text-tag-left-margin, Accessor
gtk:text-tag-left-margin-set, Accessor
gtk:text-tag-letter-spacing, Accessor
gtk:text-tag-letter-spacing-set, Accessor
gtk:text-tag-line-height, Accessor
gtk:text-tag-line-height-set, Accessor
gtk:text-tag-name, Accessor
gtk:text-tag-new, Function
gtk:text-tag-overline, Accessor
gtk:text-tag-overline-rgba, Accessor
gtk:text-tag-overline-rgba-set, Accessor
gtk:text-tag-overline-set, Accessor
gtk:text-tag-paragraph-background, Accessor
gtk:text-tag-paragraph-background-rgba, Accessor
gtk:text-tag-paragraph-background-set, Accessor
gtk:text-tag-pixels-above-lines, Accessor
gtk:text-tag-pixels-above-lines-set, Accessor
gtk:text-tag-pixels-below-lines, Accessor
gtk:text-tag-pixels-below-lines-set, Accessor
gtk:text-tag-pixels-inside-wrap, Accessor
gtk:text-tag-pixels-inside-wrap-set, Accessor
gtk:text-tag-priority, Function
gtk:text-tag-right-margin, Accessor
gtk:text-tag-right-margin-set, Accessor
gtk:text-tag-rise, Accessor
gtk:text-tag-rise-set, Accessor
gtk:text-tag-scale, Accessor
gtk:text-tag-scale-set, Accessor
gtk:text-tag-sentence, Accessor
gtk:text-tag-sentence-set, Accessor
gtk:text-tag-show-spaces, Accessor
gtk:text-tag-show-spaces-set, Accessor
gtk:text-tag-size, Accessor
gtk:text-tag-size-points, Accessor
gtk:text-tag-size-set, Accessor
gtk:text-tag-stretch, Accessor
gtk:text-tag-stretch-set, Accessor
gtk:text-tag-strikethrough, Accessor
gtk:text-tag-strikethrough-rgba, Accessor
gtk:text-tag-strikethrough-rgba-set, Accessor
gtk:text-tag-strikethrough-set, Accessor
gtk:text-tag-style, Accessor
gtk:text-tag-style-set, Accessor
gtk:text-tag-table-add, Function
gtk:text-tag-table-foreach, Function
gtk:text-tag-table-lookup, Function
gtk:text-tag-table-new, Function
gtk:text-tag-table-remove, Function
gtk:text-tag-table-size, Function
gtk:text-tag-tabs, Accessor
gtk:text-tag-tabs-set, Accessor
gtk:text-tag-text-transform, Accessor
gtk:text-tag-text-transform-set, Accessor
gtk:text-tag-underline, Accessor
gtk:text-tag-underline-rgba, Accessor
gtk:text-tag-underline-rgba-set, Accessor
gtk:text-tag-underline-set, Accessor
gtk:text-tag-variant, Accessor
gtk:text-tag-variant-set, Accessor
gtk:text-tag-weight, Accessor
gtk:text-tag-weight-set, Accessor
gtk:text-tag-word, Accessor
gtk:text-tag-word-set, Accessor
gtk:text-tag-wrap-mode, Accessor
gtk:text-tag-wrap-mode-set, Accessor
gtk:text-text-length, Function
gtk:text-truncate-multiline, Accessor
gtk:text-unset-invisible-char, Function
gtk:text-view-accepts-tab, Accessor
gtk:text-view-add-child-at-anchor, Function
gtk:text-view-add-overlay, Function
gtk:text-view-bottom-margin, Accessor
gtk:text-view-buffer, Accessor
gtk:text-view-buffer-to-window-coords, Function
gtk:text-view-cursor-locations, Function
gtk:text-view-cursor-visible, Accessor
gtk:text-view-editable, Accessor
gtk:text-view-extra-menu, Accessor
gtk:text-view-gutter, Function
gtk:text-view-im-context-filter-keypress, Function
gtk:text-view-im-module, Accessor
gtk:text-view-indent, Accessor
gtk:text-view-input-hints, Accessor
gtk:text-view-input-purpose, Accessor
gtk:text-view-iter-at-location, Function
gtk:text-view-iter-at-position, Function
gtk:text-view-iter-location, Function
gtk:text-view-justification, Accessor
gtk:text-view-left-margin, Accessor
gtk:text-view-line-at-y, Function
gtk:text-view-line-yrange, Function
gtk:text-view-ltr-context, Function
gtk:text-view-monospace, Accessor
gtk:text-view-move-display-line, Function
gtk:text-view-move-mark-onscreen, Function
gtk:text-view-move-overlay, Function
gtk:text-view-move-visually, Function
gtk:text-view-new, Function
gtk:text-view-new-with-buffer, Function
gtk:text-view-overwrite, Accessor
gtk:text-view-pixels-above-lines, Accessor
gtk:text-view-pixels-below-lines, Accessor
gtk:text-view-pixels-inside-wrap, Accessor
gtk:text-view-place-cursor-onscreen, Function
gtk:text-view-remove, Function
gtk:text-view-reset-cursor-blink, Function
gtk:text-view-reset-im-context, Function
gtk:text-view-right-margin, Accessor
gtk:text-view-rtl-context, Function
gtk:text-view-scroll-mark-onscreen, Function
gtk:text-view-scroll-to-iter, Function
gtk:text-view-scroll-to-mark, Function
gtk:text-view-starts-display-line, Function
gtk:text-view-tabs, Accessor
gtk:text-view-top-margin, Accessor
gtk:text-view-visible-rect, Function
gtk:text-view-window-to-buffer-coords, Function
gtk:text-view-wrap-mode, Accessor
gtk:text-visibility, Accessor
gtk:toggle-button-active, Accessor
gtk:toggle-button-group, Accessor
gtk:toggle-button-new, Function
gtk:toggle-button-new-with-label, Function
gtk:toggle-button-new-with-mnemonic, Function
gtk:toggle-button-toggled, Function
gtk:tooltip-set-custom, Function
gtk:tooltip-set-icon, Function
gtk:tooltip-set-icon-from-gicon, Function
gtk:tooltip-set-icon-from-icon-name, Function
gtk:tooltip-set-markup, Function
gtk:tooltip-set-text, Function
gtk:tooltip-set-tip-area, Function
gtk:tree-create-row-drag-content, Function
gtk:tree-drag-dest-drag-data-received, Function
gtk:tree-drag-dest-row-drop-possible, Function
gtk:tree-drag-source-drag-data-delete, Function
gtk:tree-drag-source-drag-data-get, Function
gtk:tree-drag-source-row-draggable, Function
gtk:tree-expander-child, Accessor
gtk:tree-expander-hide-expander, Accessor
gtk:tree-expander-indent-for-depth, Accessor
gtk:tree-expander-indent-for-icon, Accessor
gtk:tree-expander-item, Accessor
gtk:tree-expander-list-row, Accessor
gtk:tree-expander-new, Function
gtk:tree-list-model-autoexpand, Accessor
gtk:tree-list-model-child-row, Function
gtk:tree-list-model-item-type, Accessor
gtk:tree-list-model-model, Accessor
gtk:tree-list-model-n-items, Accessor
gtk:tree-list-model-new, Function
gtk:tree-list-model-passthrough, Accessor
gtk:tree-list-model-row, Function
gtk:tree-list-row-child-row, Function
gtk:tree-list-row-children, Accessor
gtk:tree-list-row-depth, Accessor
gtk:tree-list-row-expandable, Accessor
gtk:tree-list-row-expanded, Accessor
gtk:tree-list-row-is-expandable, Function
gtk:tree-list-row-item, Accessor
gtk:tree-list-row-parent, Function
gtk:tree-list-row-position, Function
gtk:tree-list-row-sorter-new, Function
gtk:tree-list-row-sorter-sorter, Accessor
gtk:tree-model-column-type, Function
gtk:tree-model-filter-child-model, Accessor
gtk:tree-model-filter-convert-child-iter-to-iter, Function
gtk:tree-model-filter-convert-child-path-to-path, Function
gtk:tree-model-filter-convert-iter-to-child-iter, Function
gtk:tree-model-filter-convert-path-to-child-path, Function
gtk:tree-model-filter-model, Function
gtk:tree-model-filter-new, Function
gtk:tree-model-filter-refilter, Function
gtk:tree-model-filter-set-modify-func, Function
gtk:tree-model-filter-set-visible-column, Function
gtk:tree-model-filter-set-visible-func, Function
gtk:tree-model-filter-virtual-root, Accessor
gtk:tree-model-flags, Function
gtk:tree-model-foreach, Function
gtk:tree-model-get, Function
gtk:tree-model-iter, Function
gtk:tree-model-iter-children, Function
gtk:tree-model-iter-first, Function
gtk:tree-model-iter-from-string, Function
gtk:tree-model-iter-has-child, Function
gtk:tree-model-iter-n-children, Function
gtk:tree-model-iter-next, Function
gtk:tree-model-iter-nth-child, Function
gtk:tree-model-iter-parent, Function
gtk:tree-model-iter-previous, Function
gtk:tree-model-n-columns, Function
gtk:tree-model-path, Function
gtk:tree-model-row-changed, Function
gtk:tree-model-row-deleted, Function
gtk:tree-model-row-has-child-toggled, Function
gtk:tree-model-row-inserted, Function
gtk:tree-model-rows-reordered, Function
gtk:tree-model-sort-convert-child-iter-to-iter, Function
gtk:tree-model-sort-convert-child-path-to-path, Function
gtk:tree-model-sort-convert-iter-to-child-iter, Function
gtk:tree-model-sort-convert-path-to-child-path, Function
gtk:tree-model-sort-iter-is-valid, Function
gtk:tree-model-sort-model, Accessor
gtk:tree-model-sort-new-with-model, Function
gtk:tree-model-sort-reset-default-sort-func, Function
gtk:tree-model-string-from-iter, Function
gtk:tree-model-value, Function
gtk:tree-path-append-index, Function
gtk:tree-path-compare, Function
gtk:tree-path-copy, Function
gtk:tree-path-depth, Function
gtk:tree-path-down, Function
gtk:tree-path-indices, Function
gtk:tree-path-is-ancestor, Function
gtk:tree-path-is-descendant, Function
gtk:tree-path-new, Function
gtk:tree-path-new-first, Function
gtk:tree-path-new-from-indices, Function
gtk:tree-path-new-from-string, Function
gtk:tree-path-next, Function
gtk:tree-path-prepend-index, Function
gtk:tree-path-prev, Function
gtk:tree-path-to-string, Function
gtk:tree-path-up, Function
gtk:tree-row-reference-copy, Function
gtk:tree-row-reference-model, Function
gtk:tree-row-reference-new, Function
gtk:tree-row-reference-path, Function
gtk:tree-row-reference-valid, Function
gtk:tree-selection-count-selected-rows, Function
gtk:tree-selection-iter-is-selected, Function
gtk:tree-selection-mode, Accessor
gtk:tree-selection-path-is-selected, Function
gtk:tree-selection-select-all, Function
gtk:tree-selection-select-iter, Function
gtk:tree-selection-select-path, Function
gtk:tree-selection-select-range, Function
gtk:tree-selection-selected, Function
gtk:tree-selection-selected-foreach, Function
gtk:tree-selection-selected-rows, Function
gtk:tree-selection-set-select-function, Function
gtk:tree-selection-tree-view, Function
gtk:tree-selection-unselect-all, Function
gtk:tree-selection-unselect-iter, Function
gtk:tree-selection-unselect-path, Function
gtk:tree-selection-unselect-range, Function
gtk:tree-sortable-has-default-sort-func, Function
gtk:tree-sortable-set-default-sort-func, Function
gtk:tree-sortable-set-sort-func, Function
gtk:tree-sortable-sort-column-changed, Function
gtk:tree-sortable-sort-column-id, Function
gtk:tree-store-append, Function
gtk:tree-store-clear, Function
gtk:tree-store-insert, Function
gtk:tree-store-insert-after, Function
gtk:tree-store-insert-before, Function
gtk:tree-store-insert-with-values, Function
gtk:tree-store-is-ancestor, Function
gtk:tree-store-iter-depth, Function
gtk:tree-store-iter-is-valid, Function
gtk:tree-store-move-after, Function
gtk:tree-store-move-before, Function
gtk:tree-store-new, Function
gtk:tree-store-prepend, Function
gtk:tree-store-remove, Function
gtk:tree-store-reorder, Function
gtk:tree-store-set, Function
gtk:tree-store-set-column-types, Function
gtk:tree-store-set-value, Function
gtk:tree-store-swap, Function
gtk:tree-view-activate-on-single-click, Accessor
gtk:tree-view-append-column, Function
gtk:tree-view-background-area, Function
gtk:tree-view-cell-area, Function
gtk:tree-view-collapse-all, Function
gtk:tree-view-collapse-row, Function
gtk:tree-view-column, Function
gtk:tree-view-column-add-attribute, Function
gtk:tree-view-column-alignment, Accessor
gtk:tree-view-column-button, Function
gtk:tree-view-column-cell-area, Accessor
gtk:tree-view-column-cell-is-visible, Function
gtk:tree-view-column-cell-position, Function
gtk:tree-view-column-cell-set-cell-data, Function
gtk:tree-view-column-cell-size, Function
gtk:tree-view-column-clear, Function
gtk:tree-view-column-clear-attributes, Function
gtk:tree-view-column-clickable, Accessor
gtk:tree-view-column-clicked, Function
gtk:tree-view-column-expand, Accessor
gtk:tree-view-column-fixed-width, Accessor
gtk:tree-view-column-focus-cell, Function
gtk:tree-view-column-max-width, Accessor
gtk:tree-view-column-min-width, Accessor
gtk:tree-view-column-new, Function
gtk:tree-view-column-new-with-area, Function
gtk:tree-view-column-new-with-attributes, Function
gtk:tree-view-column-pack-end, Function
gtk:tree-view-column-pack-start, Function
gtk:tree-view-column-queue-resize, Function
gtk:tree-view-column-reorderable, Accessor
gtk:tree-view-column-resizable, Accessor
gtk:tree-view-column-set-attributes, Function
gtk:tree-view-column-set-cell-data-func, Function
gtk:tree-view-column-sizing, Accessor
gtk:tree-view-column-sort-column-id, Accessor
gtk:tree-view-column-sort-indicator, Accessor
gtk:tree-view-column-sort-order, Accessor
gtk:tree-view-column-spacing, Accessor
gtk:tree-view-column-title, Accessor
gtk:tree-view-column-tree-view, Function
gtk:tree-view-column-visible, Accessor
gtk:tree-view-column-widget, Accessor
gtk:tree-view-column-width, Accessor
gtk:tree-view-column-x-offset, Accessor
gtk:tree-view-columns, Function
gtk:tree-view-columns-autosize, Function
gtk:tree-view-convert-bin-window-to-tree-coords, Function
gtk:tree-view-convert-bin-window-to-widget-coords, Function
gtk:tree-view-convert-tree-to-bin-window-coords, Function
gtk:tree-view-convert-tree-to-widget-coords, Function
gtk:tree-view-convert-widget-to-bin-window-coords, Function
gtk:tree-view-convert-widget-to-tree-coords, Function
gtk:tree-view-create-row-drag-icon, Function
gtk:tree-view-enable-grid-lines, Accessor
gtk:tree-view-enable-model-drag-dest, Function
gtk:tree-view-enable-model-drag-source, Function
gtk:tree-view-enable-search, Accessor
gtk:tree-view-enable-tree-lines, Accessor
gtk:tree-view-expand-all, Function
gtk:tree-view-expand-row, Function
gtk:tree-view-expand-to-path, Function
gtk:tree-view-expander-column, Accessor
gtk:tree-view-fixed-height-mode, Accessor
gtk:tree-view-get-cursor, Function
gtk:tree-view-get-dest-row-at-pos, Function
gtk:tree-view-get-drag-dest-row, Function
gtk:tree-view-grid-lines, Function
gtk:tree-view-headers-clickable, Accessor
gtk:tree-view-headers-visible, Accessor
gtk:tree-view-hover-expand, Accessor
gtk:tree-view-hover-selection, Accessor
gtk:tree-view-insert-column, Function
gtk:tree-view-insert-column-with-attributes, Function
gtk:tree-view-insert-column-with-data-func, Function
gtk:tree-view-is-blank-at-pos, Function
gtk:tree-view-is-rubber-banding-active, Function
gtk:tree-view-level-indentation, Accessor
gtk:tree-view-map-expanded-rows, Function
gtk:tree-view-model, Accessor
gtk:tree-view-move-column-after, Function
gtk:tree-view-n-columns, Function
gtk:tree-view-new, Function
gtk:tree-view-new-with-model, Function
gtk:tree-view-path-at-pos, Function
gtk:tree-view-remove-column, Function
gtk:tree-view-reorderable, Accessor
gtk:tree-view-row-activated, Function
gtk:tree-view-row-expanded, Function
gtk:tree-view-rubber-banding, Accessor
gtk:tree-view-scroll-to-cell, Function
gtk:tree-view-scroll-to-point, Function
gtk:tree-view-search-column, Accessor
gtk:tree-view-search-entry, Function
gtk:tree-view-selection, Function
gtk:tree-view-set-column-drag-function, Function
gtk:tree-view-set-cursor, Function
gtk:tree-view-set-cursor-on-cell, Function
gtk:tree-view-set-drag-dest-row, Function
gtk:tree-view-set-row-separator-func, Function
gtk:tree-view-set-search-equal-func, Function
gtk:tree-view-set-tooltip-cell, Function
gtk:tree-view-set-tooltip-row, Function
gtk:tree-view-show-expanders, Accessor
gtk:tree-view-tooltip-column, Accessor
gtk:tree-view-tooltip-context, Function
gtk:tree-view-unset-rows-drag-dest, Function
gtk:tree-view-unset-rows-drag-source, Function
gtk:tree-view-visible-range, Function
gtk:tree-view-visible-rect, Function
gtk:uri-launcher-launch, Function
gtk:uri-launcher-launch-finish, Function
gtk:uri-launcher-new, Function
gtk:uri-launcher-uri, Accessor
gtk:value-expression, Function
gtk:video-autoplay, Accessor
gtk:video-file, Accessor
gtk:video-graphics-offload, Accessor
gtk:video-loop, Accessor
gtk:video-media-stream, Accessor
gtk:video-new, Function
gtk:video-new-for-file, Function
gtk:video-new-for-filename, Function
gtk:video-new-for-media-stream, Function
gtk:video-new-for-resource, Function
gtk:video-set-filename, Function
gtk:video-set-resource, Function
gtk:viewport-child, Accessor
gtk:viewport-new, Function
gtk:viewport-scroll-to, Function
gtk:viewport-scroll-to-focus, Accessor
gtk:volume-button-new, Function
gtk:volume-button-use-symbolic, Accessor
gtk:widget-activate, Function
gtk:widget-activate-action, Function
gtk:widget-add-controller, Function
gtk:widget-add-css-class, Function
gtk:widget-add-mnemonic-label, Function
gtk:widget-add-provider, Function
gtk:widget-add-tick-callback, Function
gtk:widget-allocate, Function
gtk:widget-allocated-baseline, Function
gtk:widget-allocated-height, Function
gtk:widget-allocated-width, Function
gtk:widget-allocation, Function
gtk:widget-ancestor, Function
gtk:widget-baseline, Function
gtk:widget-can-focus, Accessor
gtk:widget-can-target, Accessor
gtk:widget-child-focus, Function
gtk:widget-child-visible, Function
gtk:widget-class-accessible-role, Function
gtk:widget-class-add-shortcut, Function
gtk:widget-class-bind-template-callback, Function  (undocumented)
gtk:widget-class-bind-template-child, Function
gtk:widget-class-css-name, Function
gtk:widget-class-layout-manager-type, Function
gtk:widget-class-set-template, Function
gtk:widget-class-set-template-from-resource, Function
gtk:widget-class-set-template-scope, Function  (undocumented)
gtk:widget-clipboard, Function
gtk:widget-color, Function
gtk:widget-compute-bounds, Function
gtk:widget-compute-expand, Function
gtk:widget-compute-point, Function
gtk:widget-compute-transform, Function
gtk:widget-contains, Function
gtk:widget-create-pango-context, Function
gtk:widget-create-pango-layout, Function
gtk:widget-css-classes, Accessor
gtk:widget-css-name, Accessor
gtk:widget-cursor, Accessor
gtk:widget-default-direction, Function
gtk:widget-direction, Function
gtk:widget-display, Function
gtk:widget-dispose-template, Function
gtk:widget-error-bell, Function
gtk:widget-first-child, Function
gtk:widget-focus-child, Function
gtk:widget-focus-on-click, Accessor
gtk:widget-focusable, Accessor
gtk:widget-font-map, Function
gtk:widget-font-options, Function
gtk:widget-frame-clock, Function
gtk:widget-get-parent, Function  (undocumented)
gtk:widget-grab-focus, Function
gtk:widget-halign, Accessor
gtk:widget-has-css-class, Function
gtk:widget-has-default, Accessor
gtk:widget-has-focus, Accessor
gtk:widget-has-tooltip, Accessor
gtk:widget-has-visible-focus, Function
gtk:widget-height, Function
gtk:widget-height-request, Accessor
gtk:widget-hexpand, Accessor
gtk:widget-hexpand-set, Accessor
gtk:widget-hide, Function
gtk:widget-in-destruction, Function
gtk:widget-init-template, Function
gtk:widget-insert-action-group, Function
gtk:widget-insert-after, Function
gtk:widget-insert-before, Function
gtk:widget-is-ancestor, Function
gtk:widget-is-drawable, Function
gtk:widget-is-focus, Function
gtk:widget-is-sensitive, Function
gtk:widget-is-visible, Function
gtk:widget-keynav-failed, Function
gtk:widget-last-child, Function
gtk:widget-layout-manager, Accessor
gtk:widget-list-mnemonic-labels, Function
gtk:widget-map, Function
gtk:widget-mapped, Function
gtk:widget-margin-bottom, Accessor
gtk:widget-margin-end, Accessor
gtk:widget-margin-start, Accessor
gtk:widget-margin-top, Accessor
gtk:widget-measure, Function
gtk:widget-mnemonic-activate, Function
gtk:widget-name, Accessor
gtk:widget-native, Function
gtk:widget-next-sibling, Function
gtk:widget-observe-children, Function
gtk:widget-observe-controllers, Function
gtk:widget-opacity, Accessor
gtk:widget-overflow, Accessor
gtk:widget-paintable-new, Function
gtk:widget-paintable-widget, Accessor
gtk:widget-pango-context, Function
gtk:widget-parent, Accessor
gtk:widget-pick, Function
gtk:widget-preferred-size, Function
gtk:widget-prev-sibling, Function
gtk:widget-primary-clipboard, Function
gtk:widget-queue-allocate, Function
gtk:widget-queue-draw, Function
gtk:widget-queue-resize, Function
gtk:widget-realize, Function
gtk:widget-realized, Function
gtk:widget-receives-default, Accessor
gtk:widget-remove-controller, Function
gtk:widget-remove-css-class, Function
gtk:widget-remove-mnemonic-label, Function
gtk:widget-remove-provider, Function
gtk:widget-remove-tick-callback, Function
gtk:widget-request-mode, Function
gtk:widget-root, Accessor
gtk:widget-scale-factor, Accessor
gtk:widget-sensitive, Accessor
gtk:widget-set-cursor-from-name, Function
gtk:widget-set-parent, Function
gtk:widget-settings, Function
gtk:widget-should-layout, Function
gtk:widget-show, Function
gtk:widget-size, Function
gtk:widget-size-allocate, Function
gtk:widget-size-request, Function
gtk:widget-snapshot, Function
gtk:widget-snapshot-child, Function
gtk:widget-state-flags, Function
gtk:widget-style-context, Function
gtk:widget-template-child, Function
gtk:widget-tooltip-markup, Accessor
gtk:widget-tooltip-text, Accessor
gtk:widget-translate-coordinates, Function
gtk:widget-trigger-tooltip-query, Function
gtk:widget-unmap, Function
gtk:widget-unparent, Function
gtk:widget-unrealize, Function
gtk:widget-unset-state-flags, Function
gtk:widget-valign, Accessor
gtk:widget-vexpand, Accessor
gtk:widget-vexpand-set, Accessor
gtk:widget-visible, Accessor
gtk:widget-width, Function
gtk:widget-width-request, Accessor
gtk:window-application, Accessor
gtk:window-child, Accessor
gtk:window-close, Function
gtk:window-controls-decoration-layout, Accessor
gtk:window-controls-empty, Accessor
gtk:window-controls-new, Function
gtk:window-controls-side, Accessor
gtk:window-decorated, Accessor
gtk:window-default-height, Accessor
gtk:window-default-icon-name, Function
gtk:window-default-size, Function
gtk:window-default-widget, Accessor
gtk:window-default-width, Accessor
gtk:window-deletable, Accessor
gtk:window-destroy, Function
gtk:window-destroy-with-parent, Accessor
gtk:window-display, Accessor
gtk:window-focus-visible, Accessor
gtk:window-focus-widget, Accessor
gtk:window-fullscreen, Function
gtk:window-fullscreen-on-monitor, Function
gtk:window-fullscreened, Accessor
gtk:window-group, Function
gtk:window-group-add-window, Function
gtk:window-group-list-windows, Function
gtk:window-group-new, Function
gtk:window-group-remove-window, Function
gtk:window-handle-child, Accessor
gtk:window-handle-menubar-accel, Accessor
gtk:window-handle-new, Function
gtk:window-has-group, Function
gtk:window-hide-on-close, Accessor
gtk:window-icon-name, Accessor
gtk:window-is-active, Accessor
gtk:window-is-fullscreen, Function
gtk:window-is-maximized, Function
gtk:window-is-suspended, Function
gtk:window-list-toplevels, Function
gtk:window-maximize, Function
gtk:window-maximized, Accessor
gtk:window-minimize, Function
gtk:window-mnemonics-visible, Accessor
gtk:window-modal, Accessor
gtk:window-new, Function
gtk:window-present, Function
gtk:window-present-with-time, Function
gtk:window-resizable, Accessor
gtk:window-set-auto-startup-notification, Function
gtk:window-set-interactive-debugging, Function
gtk:window-startup-id, Accessor
gtk:window-suspended, Accessor
gtk:window-title, Accessor
gtk:window-titlebar, Accessor
gtk:window-toplevels, Function
gtk:window-transient-for, Accessor
gtk:window-unfullscreen, Function
gtk:window-unmaximize, Function
gtk:window-unminimize, Function
gtk:accessible-announcement-priority, GEnum
gtk:accessible-autocomplete, GEnum
gtk:accessible-invalid-state, GEnum
gtk:accessible-platform-state, GEnum
gtk:accessible-property, GEnum
gtk:accessible-relation, GEnum
gtk:accessible-role, GEnum
gtk:accessible-sort, GEnum
gtk:accessible-state, GEnum
gtk:accessible-text-content-change, GEnum
gtk:accessible-text-granularity, GEnum
gtk:accessible-tristate, GEnum
gtk:align, GEnum
gtk:application-inhibit-flags, GFlags
gtk:arrow-type, GEnum
gtk:assistant-page-func, Callback
gtk:assistant-page-type, GEnum
gtk:baseline-position, GEnum
gtk:bitset-iter, CStruct
gtk:border-style, GEnum
gtk:builder-closure-flags, GFlags
gtk:buttons-type, GEnum
gtk:cell-alloc-callback, Callback
gtk:cell-callback, Callback
gtk:cell-layout-data-func, Callback
gtk:cell-renderer-accel-mode, GEnum
gtk:cell-renderer-mode, GEnum
gtk:cell-renderer-state, GFlags
gtk:collation, GEnum
gtk:constraint-attribute, GEnum
gtk:constraint-relation, GEnum
gtk:constraint-strength, GEnum
gtk:constraint-vfl-parser-error, GEnum
gtk:content-fit, GEnum
gtk:corner-type, GEnum
gtk:css-location, CStruct
gtk:custom-filter-func, Callback
gtk:delete-type, GEnum
gtk:dialog-flags, GFlags
gtk:direction-type, GEnum
gtk:drawing-area-draw-func, Callback
gtk:entry-completion-match-func, Callback
gtk:entry-icon-position, GEnum
gtk:event-controller-scroll-flags, GFlags
gtk:event-sequence-state, GEnum
gtk:expression-notify, Callback
gtk:file-chooser-action, GEnum
gtk:filter-change, GEnum
gtk:filter-match, GEnum
gtk:flow-box-create-widget-func, Callback
gtk:flow-box-filter-func, Callback
gtk:flow-box-foreach-func, Callback
gtk:flow-box-sort-func, Callback
gtk:font-chooser-level, GFlags
gtk:font-filter-func, Callback
gtk:font-level, GEnum
gtk:font-rendering, GEnum
gtk:graphics-offload-enabled, GEnum
gtk:icon-lookup-flags, GFlags
gtk:icon-size, GEnum
gtk:icon-view-drop-position, GEnum
gtk:icon-view-foreach-func, Callback
gtk:image-type, GEnum
gtk:input-hints, GFlags
gtk:input-purpose, GEnum
gtk:inscription-overflow, GEnum
gtk:justification, GEnum
gtk:level-bar-mode, GEnum
gtk:license, GEnum
gtk:list-box-create-widget-func, Callback
gtk:list-box-filter-func, Callback
gtk:list-box-foreach-func, Callback
gtk:list-box-sort-func, Callback
gtk:list-box-update-header-func, Callback
gtk:list-list-model-item-type, Symbol  (undocumented)
gtk:list-scroll-flags, GFlags
gtk:list-tab-behavior, GEnum
gtk:map-list-model-map-func, Callback
gtk:menu-button-create-popup-func, Callback
gtk:message-type, GEnum
gtk:movement-step, GEnum
gtk:natural-wrap-mode, GEnum
gtk:notebook-tab, GEnum
gtk:number-up-layout, GEnum
gtk:ordering, GEnum
gtk:orientation, GEnum
gtk:overflow, GEnum
gtk:pack-type, GEnum
gtk:pad-action-type, GEnum
gtk:page-orientation, GEnum
gtk:page-set, GEnum
gtk:page-setup-done-func, Callback
gtk:pan-direction, GEnum
gtk:pick-flags, GFlags
gtk:policy-type, GEnum
gtk:popover-menu-flags, GFlags
gtk:position-type, GEnum
gtk:print-capabilities, GFlags
gtk:print-duplex, GEnum
gtk:print-job-complete-func, Callback
gtk:print-operation-action, GEnum
gtk:print-operation-result, GEnum
gtk:print-pages, GEnum
gtk:print-quality, GEnum
gtk:print-settings-func, Callback
gtk:print-status, GEnum
gtk:printer-func, Callback
gtk:propagation-limit, GEnum
gtk:propagation-phase, GEnum
gtk:response-type, GEnum
gtk:revealer-transition-type, GEnum
gtk:scale-format-value-func, Callback
gtk:scroll-type, GEnum
gtk:scrollable-policy, GEnum
gtk:selection-mode, GEnum
gtk:sensitivity-type, GEnum
gtk:shortcut-action-flags, GFlags
gtk:shortcut-func, Callback
gtk:shortcut-scope, GEnum
gtk:shortcut-type, GEnum
gtk:size-group-mode, GEnum
gtk:size-request-mode, GEnum
gtk:sort-type, GEnum
gtk:sorter-change, GEnum
gtk:sorter-order, GEnum
gtk:spin-button-update-policy, GEnum
gtk:spin-type, GEnum
gtk:stack-transition-type, GEnum
gtk:state-flags, GFlags
gtk:string-filter-match-mode, GEnum
gtk:style-context-print-flags, GFlags
gtk:symbolic-color, GEnum
gtk:system-setting, GEnum
gtk:text-buffer-commit-notify, Callback
gtk:text-buffer-notify-flags, GFlags
gtk:text-char-predicate, Callback
gtk:text-direction, GEnum
gtk:text-extend-selection, GEnum
gtk:text-search-flags, GFlags
gtk:text-tag-table-foreach-func, Callback
gtk:text-window-type, GEnum
gtk:tick-callback, Callback
gtk:tree-cell-data-func, Callback
gtk:tree-iter-compare-func, Callback
gtk:tree-list-model-create-model-func, Callback
gtk:tree-model-filter-modify-func, Callback
gtk:tree-model-filter-visible-func, Callback
gtk:tree-model-flags, GFlags
gtk:tree-model-foreach-func, Callback
gtk:tree-selection-foreach-func, Callback
gtk:tree-selection-func, Callback
gtk:tree-view-column-drop-func, Callback
gtk:tree-view-column-sizing, GEnum
gtk:tree-view-drop-position, GEnum
gtk:tree-view-grid-lines, GEnum
gtk:tree-view-mapping-func, Callback
gtk:tree-view-row-separator-func, Callback
gtk:tree-view-search-equal-func, Callback
gtk:unit, GEnum
gtk:wrap-mode, GEnum
gtk:+invalid-list-position+, Constant
gtk:+priority-application+, Constant
gtk:+priority-fallback+, Constant
gtk:+priority-settings+, Constant
gtk:+priority-theme+, Constant
gtk:+priority-user+, Constant
gtk:+tree-sortable-default-sort-column-id+, Constant
gtk:+tree-sortable-unsorted-sort-column-id+, Constant
pango:attr-iterator, GBoxed
pango:attr-list, GBoxed
pango:attribute, GBoxed
pango:cairo-font, Interface
pango:cairo-font-map, Interface
pango:color, GBoxed
pango:context, Class
pango:coverage, Class
pango:font, Class
pango:font-description, GBoxed
pango:font-face, Class
pango:font-family, Class
pango:font-map, Class
pango:font-metrics, GBoxed
pango:fontset, Class
pango:glyph-item, GBoxed
pango:glyph-string, GBoxed
pango:item, GBoxed
pango:language, GBoxed
pango:layout, Class
pango:layout-iter, GBoxed
pango:layout-line, GBoxed
pango:matrix, GBoxed
pango:renderer, Class
pango:tab-array, GBoxed
pango:analysis-extra-attrs, Accessor
pango:analysis-flags, Accessor
pango:analysis-font, Accessor
pango:analysis-gravity, Accessor
pango:analysis-language, Accessor
pango:analysis-level, Accessor
pango:analysis-script, Accessor
pango:ascent, Function
pango:attr-allow-breaks-new, Function
pango:attr-background-alpha-new, Function
pango:attr-background-new, Function
pango:attr-fallback-new, Function
pango:attr-family-new, Function
pango:attr-font-desc-new, Function
pango:attr-font-features-new, Function
pango:attr-foreground-alpha-new, Function
pango:attr-foreground-new, Function
pango:attr-gravity-hint-new, Function
pango:attr-gravity-new, Function
pango:attr-insert-hyphens-new, Function
pango:attr-iterator-attrs, Function
pango:attr-iterator-copy, Function
pango:attr-iterator-font, Function
pango:attr-iterator-get, Function
pango:attr-iterator-next, Function
pango:attr-iterator-range, Function
pango:attr-language-new, Function
pango:attr-letter-spacing-new, Function
pango:attr-list-attributes, Function
pango:attr-list-change, Function
pango:attr-list-copy, Function
pango:attr-list-equal, Function
pango:attr-list-filter, Function
pango:attr-list-from-string, Function
pango:attr-list-insert, Function
pango:attr-list-insert-before, Function
pango:attr-list-iterator, Function
pango:attr-list-new, Function
pango:attr-list-splice, Function
pango:attr-list-to-string, Function
pango:attr-list-update, Function
pango:attr-overline-color-new, Function
pango:attr-overline-new, Function
pango:attr-rise-new, Function
pango:attr-scale-new, Function
pango:attr-shape-new, Function
pango:attr-show-new, Function
pango:attr-size-new, Function
pango:attr-size-new-absolute, Function
pango:attr-stretch-new, Function
pango:attr-strikethrough-color-new, Function
pango:attr-strikethrough-new, Function
pango:attr-style-new, Function
pango:attr-type-name, Function
pango:attr-type-register, Function
pango:attr-underline-color-new, Function
pango:attr-underline-new, Function
pango:attr-variant-new, Function
pango:attr-weight-new, Function
pango:attribute-copy, Function
pango:attribute-end-index, Accessor
pango:attribute-equal, Function
pango:attribute-start-index, Accessor
pango:attribute-type, Accessor
pango:cairo-context-font-options, Function
pango:cairo-context-resolution, Function
pango:cairo-create-context, Function
pango:cairo-create-layout, Function
pango:cairo-error-underline-path, Function
pango:cairo-font-map-default, Function
pango:cairo-font-map-font-type, Function
pango:cairo-font-map-new, Function
pango:cairo-font-map-new-for-font-type, Function
pango:cairo-font-map-resolution, Function
pango:cairo-glyph-string-path, Function
pango:cairo-layout-line-path, Function
pango:cairo-layout-path, Function
pango:cairo-show-error-underline, Function
pango:cairo-show-glyph-item, Function
pango:cairo-show-glyph-string, Function
pango:cairo-show-layout, Function
pango:cairo-show-layout-line, Function
pango:cairo-update-context, Function
pango:cairo-update-layout, Function
pango:color-blue, Accessor
pango:color-copy, Function
pango:color-green, Accessor
pango:color-new, Function
pango:color-parse, Function
pango:color-parse-with-alpha, Function
pango:color-red, Accessor
pango:color-to-string, Function
pango:context-base-dir, Function
pango:context-base-gravity, Function
pango:context-changed, Function
pango:context-font-description, Function
pango:context-font-map, Function
pango:context-gravity, Function
pango:context-gravity-hint, Function
pango:context-language, Function
pango:context-list-families, Function
pango:context-load-font, Function
pango:context-load-fontset, Function
pango:context-matrix, Function
pango:context-metrics, Function
pango:context-new, Function
pango:context-round-glyph-positions, Function
pango:context-serial, Function
pango:coverage-get, Function
pango:coverage-new, Function
pango:coverage-set, Function
pango:descent, Function
pango:extents-to-pixels, Function
pango:find-base-dir, Function
pango:font-coverage, Function
pango:font-describe, Function
pango:font-describe-with-absolute-size, Function
pango:font-description-better-match, Function
pango:font-description-copy, Function
pango:font-description-equal, Function
pango:font-description-family, Function
pango:font-description-from-string, Function
pango:font-description-gravity, Function
pango:font-description-hash, Function
pango:font-description-merge, Function
pango:font-description-new, Function
pango:font-description-set-absolute-size, Function
pango:font-description-set-fields, Function
pango:font-description-size, Function
pango:font-description-size-is-absolute, Function
pango:font-description-stretch, Function
pango:font-description-style, Function
pango:font-description-to-filename, Function
pango:font-description-to-string, Function
pango:font-description-unset-fields, Function
pango:font-description-variant, Function
pango:font-description-variations, Function
pango:font-description-weight, Function
pango:font-deserialize, Function
pango:font-face, Function
pango:font-face-describe, Function
pango:font-face-face-name, Function
pango:font-face-family, Function
pango:font-face-is-synthesized, Function
pango:font-face-list-sizes, Function
pango:font-family-face, Function
pango:font-family-is-monospace, Accessor
pango:font-family-is-variable, Accessor
pango:font-family-item-type, Accessor
pango:font-family-list-faces, Function
pango:font-family-n-items, Accessor
pango:font-family-name, Accessor
pango:font-font-map, Function
pango:font-glyph-extents, Function
pango:font-has-char, Function
pango:font-languages, Function
pango:font-map-changed, Function
pango:font-map-create-context, Function
pango:font-map-family, Function
pango:font-map-item-type, Accessor
pango:font-map-list-families, Function
pango:font-map-load-font, Function
pango:font-map-load-fontset, Function
pango:font-map-n-items, Accessor
pango:font-map-serial, Function
pango:font-metrics, Function
pango:font-metrics-approximate-char-width, Function
pango:font-metrics-approximate-digit-width, Function
pango:font-metrics-ascent, Function
pango:font-metrics-descent, Function
pango:font-metrics-height, Function
pango:font-metrics-strikethrough-position, Function
pango:font-metrics-strikethrough-thickness, Function
pango:font-metrics-underline-position, Function
pango:font-metrics-underline-thickness, Function
pango:font-serialize, Function
pango:fontset-font, Function
pango:fontset-foreach, Function
pango:fontset-metrics, Function
pango:glyph-item-copy, Function  (undocumented)
pango:glyph-item-split, Function  (undocumented)
pango:glyph-string-copy, Function  (undocumented)
pango:glyph-string-extents, Function  (undocumented)
pango:glyph-string-extents-range, Function  (undocumented)
pango:glyph-string-index-to-x, Function  (undocumented)
pango:glyph-string-logical-widths, Function  (undocumented)
pango:glyph-string-new, Function  (undocumented)
pango:glyph-string-set-size, Function  (undocumented)
pango:glyph-string-width, Function  (undocumented)
pango:glyph-string-x-to-index, Function  (undocumented)
pango:gravity-for-matrix, Function
pango:gravity-for-script, Function
pango:gravity-for-script-and-width, Function
pango:gravity-to-rotation, Function
pango:item-analysis, Accessor
pango:item-apply-attrs, Function
pango:item-copy, Function
pango:item-length, Accessor
pango:item-new, Function
pango:item-num-chars, Accessor
pango:item-offset, Accessor
pango:item-split, Function
pango:itemize, Function
pango:itemize-with-base-dir, Function
pango:language-default, Function
pango:language-from-string, Function
pango:language-includes-script, Function
pango:language-matches, Function
pango:language-preferred, Function
pango:language-sample-string, Function
pango:language-scripts, Function
pango:language-to-string, Function
pango:layout-alignment, Function
pango:layout-attributes, Function
pango:layout-auto-dir, Function
pango:layout-baseline, Function
pango:layout-character-count, Function
pango:layout-context, Function
pango:layout-context-changed, Function
pango:layout-copy, Function
pango:layout-cursor-pos, Function
pango:layout-direction, Function
pango:layout-ellipsize, Function
pango:layout-extents, Function
pango:layout-font-description, Function
pango:layout-height, Function
pango:layout-indent, Function
pango:layout-index-to-line-x, Function
pango:layout-index-to-pos, Function
pango:layout-is-ellipsized, Function
pango:layout-is-wrapped, Function
pango:layout-iter, Function
pango:layout-iter-at-last-line, Function
pango:layout-iter-baseline, Function
pango:layout-iter-char-extents, Function
pango:layout-iter-cluster-extents, Function
pango:layout-iter-copy, Function
pango:layout-iter-index, Function
pango:layout-iter-layout, Function
pango:layout-iter-layout-extents, Function
pango:layout-iter-line, Function
pango:layout-iter-line-extents, Function
pango:layout-iter-line-readonly, Function
pango:layout-iter-line-yrange, Function
pango:layout-iter-next-char, Function
pango:layout-iter-next-cluster, Function
pango:layout-iter-next-line, Function
pango:layout-iter-next-run, Function
pango:layout-iter-run, Function
pango:layout-iter-run-extents, Function
pango:layout-iter-run-readonly, Function
pango:layout-justify, Function
pango:layout-line, Function
pango:layout-line-count, Function
pango:layout-line-extents, Function
pango:layout-line-height, Function
pango:layout-line-index-to-x, Function
pango:layout-line-is-paragraph-start, Function
pango:layout-line-length, Function
pango:layout-line-pixel-extents, Function
pango:layout-line-readonly, Function
pango:layout-line-resolved-direction, Function
pango:layout-line-spacing, Function
pango:layout-line-start-index, Function
pango:layout-line-x-ranges, Function
pango:layout-line-x-to-index, Function
pango:layout-lines, Function
pango:layout-lines-readonly, Function
pango:layout-move-cursor-visually, Function
pango:layout-new, Function
pango:layout-pixel-extents, Function
pango:layout-pixel-size, Function
pango:layout-serial, Function
pango:layout-set-markup, Function
pango:layout-set-markup-with-accel, Function
pango:layout-single-paragraph-mode, Function
pango:layout-size, Function
pango:layout-spacing, Function
pango:layout-tabs, Function
pango:layout-text, Function
pango:layout-unknown-glyphs-count, Function
pango:layout-width, Function
pango:layout-wrap, Function
pango:layout-xy-to-index, Function
pango:lbearing, Function
pango:matrix-concat, Function
pango:matrix-copy, Function
pango:matrix-font-scale-factor, Function
pango:matrix-font-scale-factors, Function
pango:matrix-init, Function
pango:matrix-new, Function
pango:matrix-rotate, Function
pango:matrix-scale, Function
pango:matrix-slant-ratio, Function
pango:matrix-to-float, Function
pango:matrix-transform-distance, Function
pango:matrix-transform-pixel-rectangle, Function
pango:matrix-transform-point, Function
pango:matrix-transform-rectangle, Function
pango:matrix-translate, Function
pango:matrix-x0, Accessor
pango:matrix-xx, Accessor
pango:matrix-xy, Accessor
pango:matrix-y0, Accessor
pango:matrix-yx, Accessor
pango:matrix-yy, Accessor
pango:parse-markup, Function
pango:pixels, Function
pango:rbearing, Function
pango:rectangle-height, Accessor
pango:rectangle-to-integer, Function
pango:rectangle-width, Accessor
pango:rectangle-x, Accessor
pango:rectangle-y, Accessor
pango:script-sample-language, Function
pango:shape, Function
pango:shape-full, Function
pango:shape-with-flags, Function
pango:tab-array-copy, Function
pango:tab-array-decimal-point, Function
pango:tab-array-from-string, Function
pango:tab-array-new, Function
pango:tab-array-new-with-positions, Function
pango:tab-array-positions-in-pixels, Function
pango:tab-array-resize, Function
pango:tab-array-size, Function
pango:tab-array-sort, Function
pango:tab-array-tab, Function
pango:tab-array-tabs, Function
pango:tab-array-to-string, Function
pango:unichar-direction, Function
pango:version, Function
pango:version-check, Function
pango:version-string, Function
pango:with-rectangle, Macro
pango:with-rectangles, Macro
pango:alignment, GEnum
pango:analysis, CStruct
pango:attr-filter-func, Callback
pango:attr-type, GEnum
pango:baseline-shift, GEnum
pango:coverage-level, GEnum
pango:direction, GEnum
pango:ellipsize-mode, GEnum
pango:font-mask, GFlags
pango:font-scale, GEnum
pango:fontset-foreach-func, Callback
pango:glyph, Type
pango:gravity, GEnum
pango:gravity-hint, GEnum
pango:overline, GEnum
pango:rectangle, CStruct
pango:render-part, GEnum
pango:script, GEnum
pango:shape-flags, GFlags
pango:show-flags, GFlags
pango:stretch, GEnum
pango:style, GEnum
pango:tab-align, GEnum
pango:text-transform, GEnum
pango:underline, GEnum
pango:variant, GEnum
pango:weight, GEnum
pango:wrap-mode, GEnum
pango:+scale+, Constant
pango:+scale-large+, Constant
pango:+scale-medium+, Constant
pango:+scale-small+, Constant
pango:+scale-x-large+, Constant
pango:+scale-x-small+, Constant
pango:+scale-xx-large+, Constant
pango:+scale-xx-small+, Constant