This document is for the GTK 4 library, version 3.96.0 . The latest versions can be found online at If you are looking for the older GTK 3 series of libraries, see

I. GTK Overview
Getting Started with GTK
Building user interfaces
Building applications
A trivial application
Populating the window
Opening files
An application menu
A preference dialog
Adding a search bar
Adding a side bar
Header bar
Custom Drawing
Mailing lists and bug reports — Getting help with GTK
Common Questions — Find answers to common questions in the GTK manual
The GTK Drawing Model — How widgets draw
The GTK Input Model — input and event handling in detail
The GTK Action Model — How actions are used in GTK
II. GTK Widgets and Objects
Object Hierarchy
Widget Gallery
GListModel support
GtkFilterListModel — A list model that filters its items
GtkFlattenListModel — A list model that flattens a list of lists
GtkMapListModel — A list model that transforms its items
GtkSliceListModel — A list model that presents a slice out of a larger list
GtkSortListModel — A list model that sorts its items
GtkTreeListModel — A list model that can create child models on demand
GtkSelectionModel — An extension of the list model interface that handles selections
GtkSingleSelection — A selection model that allows selecting a single item
Application support
GtkApplication — Application class
GtkApplicationWindow — GtkWindow subclass with GtkApplication support
GtkActionable — An interface for widgets that can be associated with actions
Interface builder
GtkBuilder — Build an interface from an XML UI definition
GtkBuildable — Interface for objects that can be built by GtkBuilder
GtkRoot — Interface for root widgets
GtkWindow — Toplevel which can contain other widgets
GtkDialog — Create popup windows
GtkMessageDialog — A convenient message window
GtkAboutDialog — Display information about an application
GtkAssistant — A widget used to guide users through multi-step operations
GtkWindowGroup — Limit the effect of grabs
Layout Containers
GtkBox — A container for packing widgets in a single row or column
GtkCenterBox — A centering container
GtkGrid — Pack widgets in rows and columns
GtkRevealer — Hide and show with animation
GtkListBox — A list container
GtkFlowBox — A container that allows reflowing its children
GtkStack — A stacking container
GtkStackSwitcher — A controller for GtkStack
GtkStackSidebar — An automatic sidebar widget
GtkActionBar — A full width bar for presenting contextual actions
GtkHeaderBar — A box with a centered child
GtkOverlay — A container which overlays widgets on top of each other
GtkPaned — A widget with two adjustable panes
GtkNotebook — A tabbed notebook container
GtkExpander — A container which can hide its child
GtkOrientable — An interface for flippable widgets
GtkAspectFrame — A frame that constrains its child to a particular aspect ratio
GtkFixed — A container which allows you to position widgets at fixed coordinates
Layout Managers
GtkLayoutManager — Base class for layout manager
GtkLayoutChild — An object containing layout properties
GtkBinLayout — A layout manager for bin-like widgets
GtkBoxLayout — Layout manager for placing all children in a single row or column
GtkCustomLayout — A convenience layout manager
GtkFixedLayout — A layout manager that allows positioning at fixed coordinates
GtkGridLayout — Layout manager for grid-like widgets
Display Widgets
GtkLabel — A widget that displays a small to medium amount of text
GtkImage — A widget displaying an image
GtkPicture — A widget displaying a GdkPaintable
GtkSpinner — Show a spinner animation
GtkInfoBar — Report important messages to the user
GtkProgressBar — A widget which indicates progress visually
GtkLevelBar — A bar that can used as a level indicator
GtkStatusbar — Report messages of minor importance to the user
GtkAccelLabel — A label which displays an accelerator key on the right of the text
GtkCalendar — Displays a calendar and allows the user to select a date
Media Support
GtkVideo — A widget for displaying video
GtkMediaControls — A widget showing controls for a media stream
GtkMediaStream — Display media in GTK
GtkMediaFile — Open media files for use in GTK
Buttons and Toggles
GtkButton — A widget that emits a signal when clicked on
GtkCheckButton — Create widgets with a discrete toggle button
GtkRadioButton — A choice from multiple check buttons
GtkToggleButton — Create buttons which retain their state
GtkLinkButton — Create buttons bound to a URL
GtkMenuButton — A widget that shows a popup when clicked on
GtkSwitch — A “light switch” style toggle
GtkScaleButton — A button which pops up a scale
GtkVolumeButton — A button which pops up a volume control
GtkLockButton — A widget to unlock or lock privileged operations
GtkModelButton — A button that uses a GAction as model
Numeric and Text Data Entry
GtkEditable — Interface for text-editing widgets
GtkEntryBuffer — Text buffer for GtkEntry
GtkText — A simple single-line text entry field
GtkEntry — A single line text entry field
GtkEntryCompletion — Completion functionality for GtkEntry
GtkPasswordEntry — An entry for secrets
GtkScale — A slider widget for selecting a value from a range
GtkSpinButton — Retrieve an integer or floating-point number from the user
GtkSearchEntry — An entry which shows a search icon
GtkSearchBar — A toolbar to integrate a search entry with
Multiline Text Editor
Text Widget Overview — Overview of GtkTextBuffer, GtkTextView, and friends
GtkTextIter — Text buffer iterator
GtkTextMark — A position in the buffer preserved across buffer modifications
GtkTextBuffer — Stores attributed text for display in a GtkTextView
GtkTextTag — A tag that can be applied to text in a GtkTextBuffer
GtkTextTagTable — Collection of tags that can be used together
GtkTextView — Widget that displays a GtkTextBuffer
Tree, List and Icon Grid Widgets
Tree and List Widget Overview — Overview of GtkTreeModel, GtkTreeView, and friends
GtkTreeModel — The tree interface used by GtkTreeView
GtkTreeSelection — The selection object for GtkTreeView
GtkTreeViewColumn — A visible column in a GtkTreeView widget
GtkTreeView — A widget for displaying both trees and lists
GtkTreeView drag-and-drop — Interfaces for drag-and-drop support in GtkTreeView
GtkCellView — A widget displaying a single row of a GtkTreeModel
GtkIconView — A widget which displays a list of icons in a grid
GtkTreeSortable — The interface for sortable models used by GtkTreeView
GtkTreeModelSort — A GtkTreeModel which makes an underlying tree model sortable
GtkTreeModelFilter — A GtkTreeModel which hides parts of an underlying tree model
GtkCellLayout — An interface for packing cells
GtkCellArea — An abstract class for laying out GtkCellRenderers
GtkCellAreaBox — A cell area that renders GtkCellRenderers into a row or a column
GtkCellAreaContext — Stores geometrical information for a series of rows in a GtkCellArea
GtkCellRenderer — An object for rendering a single cell
GtkCellEditable — Interface for widgets that can be used for editing cells
GtkCellRendererAccel — Renders a keyboard accelerator in a cell
GtkCellRendererCombo — Renders a combobox in a cell
GtkCellRendererPixbuf — Renders a pixbuf in a cell
GtkCellRendererProgress — Renders numbers as progress bars
GtkCellRendererSpin — Renders a spin button in a cell
GtkCellRendererText — Renders text in a cell
GtkCellRendererToggle — Renders a toggle button in a cell
GtkCellRendererSpinner — Renders a spinning animation in a cell
GtkListStore — A list-like data structure that can be used with the GtkTreeView
GtkTreeStore — A tree-like data structure that can be used with the GtkTreeView
Menus, Combo Box, Toolbar
GtkComboBox — A widget used to choose from a list of items
GtkComboBoxText — A simple, text-only combo box
GtkMenu — A menu widget
GtkMenuBar — A subclass of GtkMenuShell which holds GtkMenuItem widgets
GtkMenuItem — The widget used for item in menus
GtkRadioMenuItem — A choice from multiple check menu items
GtkCheckMenuItem — A menu item with a check box
GtkSeparatorMenuItem — A separator used in menus
GtkToolShell — Interface for containers containing GtkToolItem widgets
GtkToolbar — Create bars of buttons and other widgets
GtkToolItem — The base class of widgets that can be added to GtkToolShell
GtkSeparatorToolItem — A toolbar item that separates groups of other toolbar items
GtkToolButton — A GtkToolItem subclass that displays buttons
GtkMenuToolButton — A GtkToolItem containing a button with an additional dropdown menu
GtkToggleToolButton — A GtkToolItem containing a toggle button
GtkRadioToolButton — A toolbar item that contains a radio button
GtkPopover — Context dependent bubbles
GtkPopoverMenu — Popovers to use as menus
GtkPopoverMenuBar — A menu bar with popovers
Selector Widgets and Dialogs
GtkColorChooser — Interface implemented by widgets for choosing colors
GtkColorButton — A button to launch a color selection dialog
GtkColorChooserWidget — A widget for choosing colors
GtkColorChooserDialog — A dialog for choosing colors
GtkFileChooser — File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog
GtkFileChooserButton — A button to launch a file selection dialog
GtkFileChooserNative — A native file chooser dialog, suitable for “File/Open” or “File/Save” commands
GtkFileChooserDialog — A file chooser dialog, suitable for “File/Open” or “File/Save” commands
GtkFileChooserWidget — A file chooser widget
GtkFileFilter — A filter for selecting a file subset
GtkFontChooser — Interface implemented by widgets displaying fonts
GtkFontButton — A button to launch a font chooser dialog
GtkFontChooserWidget — A widget for selecting fonts
GtkFontChooserDialog — A dialog for selecting fonts
Widgets for custom drawing
GtkDrawingArea — A simple widget for custom user interface elements
GtkGLArea — A widget for custom drawing with OpenGL
GtkFrame — A bin with a decorative frame and optional label
GtkSeparator — A separator widget
GtkScrollbar — A Scrollbar
GtkScrolledWindow — Adds scrollbars to its child widget
GtkScrollable — An interface for scrollable widgets
GtkViewport — An adapter which makes widgets scrollable
GtkPrintOperation — High-level Printing API
GtkPrintContext — Encapsulates context for drawing pages
GtkPrintSettings — Stores print settings
GtkPageSetup — Stores page setup information
GtkPaperSize — Support for named paper sizes
GtkPrinter — Represents a printer
GtkPrintJob — Represents a print job
GtkPrintUnixDialog — A print dialog
GtkPageSetupUnixDialog — A page setup dialog
Shortcuts Overview
GtkShortcutsWindow — Toplevel which shows help for shortcuts
GtkShortcutsSection — Represents an application mode in a GtkShortcutsWindow
GtkShortcutsGroup — Represents a group of shortcuts in a GtkShortcutsWindow
GtkShortcutsShortcut — Represents a keyboard shortcut in a GtkShortcutsWindow
GtkAdjustment — A representation of an adjustable bounded value
GtkIMContextSimple — An input method context supporting table-based input methods
GtkIMMulticontext — An input method context supporting multiple, loadable input methods
GtkSizeGroup — Grouping widgets so they request the same size
GtkSnapshot — Auxiliary object for snapshots
GtkTooltip — Add tips to your widgets
GtkWidgetPaintable — Drawing a widget elsewhere
Abstract Base Classes
GtkWidget — Base class for all widgets
GtkContainer — Base class for widgets which contain other widgets
GtkBin — A container with just one child
GtkMenuShell — A base class for menu objects
GtkRange — Base class for widgets which visualize an adjustment
GtkIMContext — Base class for input method contexts
GtkNativeDialog — Integrate with native dialogs
GtkAccessible — Accessibility support for widgets
Recently Used Documents
GtkRecentManager — Managing recently used files
Choosing from installed applications
GtkAppChooser — Interface implemented by widgets for choosing an application
GtkAppChooserButton — A button to launch an application chooser dialog
GtkAppChooserDialog — An application chooser dialog
GtkAppChooserWidget — Application chooser widget that can be embedded in other widgets
Gestures and event handling
GtkEventController — Self-contained handler of series of events
GtkEventControllerKey — Event controller for key events
GtkEventControllerLegacy — Event controller for miscellaneous events
GtkEventControllerScroll — Event controller for scroll events
GtkEventControllerMotion — Event controller for motion events
GtkGesture — Base class for gestures
GtkGestureSingle — Base class for mouse/single-touch gestures
GtkGestureDrag — Drag gesture
GtkGestureLongPress — "Press and Hold" gesture
GtkGestureClick — Multipress gesture
GtkGesturePan — Pan gesture
GtkGestureSwipe — Swipe gesture
GtkGestureRotate — Rotate gesture
GtkGestureZoom — Zoom gesture
GtkGestureStylus — Gesture for stylus input
GtkPadController — Controller for drawing tablet pads
III. GTK Core Reference
Main loop and Events — Library initialization, main event loop, and events
Version Information — Variables and functions to check the GTK+ version
Accelerator Groups — Groups of global keyboard accelerators for an entire GtkWindow
Accelerator Maps — Loadable keyboard accelerator specifications
Drag and Drop — Functions for controlling drag and drop handling
Settings — Sharing settings between applications
Bindings — Key bindings for individual widgets
Standard Enumerations — Public enumerated types used throughout GTK+
Selections — Functions for handling inter-process communication via selections
Testing — Utilities for testing GTK+ applications
Filesystem utilities — Functions for working with GIO
IV. Theming in GTK
GTK CSS Overview — Overview of CSS in GTK
GTK CSS Properties — CSS Properties in GTK
GtkStyleContext — Rendering UI elements
GtkCssProvider — CSS-like styling for widgets
GtkStyleProvider — Interface to provide style information to GtkStyleContext
GtkWidgetPath — Widget path abstraction
GtkIconTheme — Looking up icons by name
V. Migrating from Previous Versions of GTK
Migrating from GTK 2.x to GTK 4
Migrating from GTK 3.x to GTK 4
Preparation in GTK 3.x
Do not use deprecated symbols
Enable diagnostic warnings
Do not use widget style properties
Review your window creation flags
Stop using non-RGBA visuals
Stop using GtkBox:padding, GtkBox:fill and GtkBox:expand
Stop using the state argument of GtkStyleContext getters
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()
Stop using GtkButton's image-related API
Stop using GtkWidget event signals
Set a proper application ID
Changes that need to be done at the time of the switch
Convert your ui files
Stop using GdkScreen
Stop using the root window
Stop using GdkVisual
Stop using GdkDeviceManager
Adapt to GdkWindow API changes
Stop accessing GdkEvent fields
Stop using gdk_surface_set_event_compression
Stop using gdk_pointer_warp()
Adapt to coordinate API changes
Adapt to GdkKeymap API changes
Adapt to event controller API changes
Stop using GtkEventBox
Stop using GtkButtonBox
Adapt to GtkButton API changes
Adapt to GtkHeaderBar and GtkActionBar API changes
Adapt to GtkStack, GtkAssistant and GtkNotebook API changes
Adapt to GtkStyleContext API changes
Adapt to GtkCssProvider API changes
Stop using GtkContainer::border-width
Adapt to GtkWidget's size request changes
Adapt to GtkWidget's size allocation changes
Switch to GtkWidget's children APIs
Don't use -gtk-gradient in your CSS
Don't use -gtk-icon-effect in your CSS
Use gtk_widget_measure
Adapt to drawing model changes
Stop using APIs to query GdkSurfaces
Widgets are now visible by default
Adapt to changes in animated hiding and showing of widgets
Stop passing commandline arguments to gtk_init
GdkPixbuf is deemphasized
GtkWidget event signals are removed
Invalidation handling has changed
Stop using GtkWidget::draw
Window content observation has changed
The gtk_window_fullscreen_on_monitor API has changed
Adapt to cursor API changes
Adapt to icon size API changes
Convert .ui files
Adapt to changes in the GtkAssistant API
Adapt to changes in the API of GtkEntry, GtkSearchEntry and GtkSpinButton
Adapt to changes in GtkOverlay API
Use GtkFixed instead of GtkLayout
Adapt to search entry changes
Stop using child properties
Stop using tabular menus
Stop using gtk_menu_set_display()
Stop using gtk_window_activate_default()
Stop setting ::has-default and ::has-focus in .ui files
Stop using the GtkWidget::display-changed signal
GtkPopover::modal has been renamed to autohide
gtk_widget_get_surface has been removed
gtk_widget_is_toplevel has been removed
gtk_widget_get_toplevel has been removed
VI. GTK Tools
gtk4-demo — Demonstrate GTK widgets
gtk4-demo-application — Demonstrate GtkApplication
gtk4-widget-factory — Demonstrate GTK widgets
gtk4-icon-browser — List themed icons
gtk4-update-icon-cache — Icon theme caching utility
gtk4-encode-symbolic-svg — Symbolic icon conversion utility
gtk4-builder-tool — GtkBuilder file utility
gtk4-launch — Launch an application
gtk4-query-settings — Utility to print name and value of all GtkSettings properties
gtk4-broadwayd — Broadway display server
VII. GTK Platform Support
Compiling the GTK libraries — How to compile GTK itself
Compiling GTK Applications — How to compile your GTK application
Running GTK Applications — How to run and debug your GTK application
Using GTK on the X Window System — X11-specific aspects of using GTK
Using GTK on Windows — Windows-specific aspects of using GTK
Using GTK on Apple macOS — MacOS-specific aspects of using GTK
Using GTK with Broadway — HTML-specific aspects of using GTK
Using GTK with Wayland — Wayland-specific aspects of using GTK
Index of all symbols
Annotation Glossary