GTK 4 Reference Manual

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

I. Introduction
Getting Started with GTK
Hello, World
Hello World in C
Packing buttons
Custom Drawing
Drawing in response to input
Building user interfaces
Packing buttons with GtkBuilder
Building applications
A trivial application
Populating the window
Opening files
A menu
A preference dialog
Adding a search bar
Adding a side bar
Contact information and bug reports
Opening a bug or feature request
Working on GTK
Common Questions
General Questions
Which widget should I use…
Questions about GtkWidget
GtkTextView questions
GtkTreeView questions
Using cairo with GTK
II. GTK Concepts
Overview of the drawing model
Windows and events
The frame clock
The scene graph
Hierarchical drawing
Overview of GTK input and event handling
Devices and events
Event propagation
Keyboard input
Event controllers and gestures
Gesture states
Overview of actions in GTK
Basics about actions
Action state and parameters
Action scopes
Action groups and action maps
Connecting actions to widgets
Built-in Actions
III. GTK Widgets and Objects
Object Hierarchy
Widget Gallery
GListModel support
GtkBitset — Sets of integers
GtkExpression — Expressions to values
GtkFilterListModel — A list model that filters its items
GtkFilter — Filtering items
GtkCustomFilter — Filtering with callbacks
GtkMultiFilter — Combining multiple filters
GtkBoolFilter — Filtering by boolean expressions
GtkStringFilter — Filtering by strings
GtkFileFilter — Filtering files
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
GtkSorter — Sorting items
GtkCustomSorter — Sorting with a callbacks
GtkMultiSorter — Combining multiple sorters
GtkStringSorter — Sort by comparing strings
GtkNumericSorter — Sort by comparing numbers
GtkSelectionModel — An extension of the list model interface that handles selections
GtkNoSelection — A selection model that does not allow selecting anything
GtkSingleSelection — A selection model that allows selecting a single item
GtkMultiSelection — A selection model that allows selecting multiple items
GtkSelectionFilterModel — A list model that turns a selection in a model
GtkBookmarkList — A list model for recently used files
GtkDirectoryList — A list model for directory listings
GtkStringList — A list model for strings
List-based Widgets
List Widget Overview
Behind the scenes
Choosing the right model
Displaying trees
List styles
Comparison to GtkTreeView
GtkListItem — Object used to represent items of a list model
GtkListItemFactory — Mapping list items to widgets
GtkSignalListItemFactory — A listitem factory providing signals
GtkBuilderListItemFactory — A listitem factory using ui files
GtkListView — A widget for displaying lists
GtkGridView — A widget for displaying grids
GtkColumnView — A widget for displaying lists in multiple columns
GtkColumnViewColumn — The column added to GtkColumnView
GtkDropDown — Choose an item from a list
Tree support
GtkTreeListModel — A list model that can create child models on demand
GtkTreeListRow — A row in a GtkTreeListModel
GtkTreeListRowSorter — Sort trees by levels
GtkTreeExpander — An indenting expander button for use in a tree list
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
GtkBuilderScope — Bindings for GtkBuilder
GtkRoot — Interface for root widgets
GtkNative — Interface for widgets having surfaces
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
GtkNativeDialog — Integrate with native dialogs
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
GtkCenterLayout — A centering layout
GtkFixedLayout — A layout manager that allows positioning at fixed coordinates
GtkGridLayout — Layout manager for grid-like widgets
GtkOverlayLayout — Layout manager that places widgets as overlays
GtkCustomLayout — A convenience layout manager
GtkConstraintLayout — A layout manager using constraints
GtkConstraint — The description of a constraint
GtkConstraintGuide — An invisible constraint target
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
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
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
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
GtkEditableLabel — A label that can be edited
Multiline Text Editor
Text Widget Overview
Simple Example
Example of Changing Text Attributes
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
Creating a model
Creating the view component
Columns and cell renderers
Selection handling
Simple Example
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
GtkComboBox — A widget used to choose from a list of items
GtkComboBoxText — A simple, text-only combo box
GtkPopover — Context dependent bubbles
GtkPopoverMenu — Popovers to use as menus
GtkPopoverMenuBar — A menu bar with popovers
GtkDropDown — Choose an item from a list
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
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
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
GtkEmojiChooser — A popover to choose an Emoji character
Widgets for custom drawing
GtkDrawingArea — A simple widget for drawing with cairo
GtkGLArea — A widget for custom drawing with OpenGL
GtkFrame — A widget 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
GtkShortcutLabel — Displays a keyboard shortcut
GTK Accessibility
The standard accessibility interface
Accessible roles and attributes
Application development rules
Authoring practices
Hiding UI elements from the accessible tree
Design patterns and custom widgets
GtkAccessible — Accessible interface
GtkATContext — An object communicating to Assistive Technologies
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
GtkWindowControls — A widget displaying window buttons
GtkWindowHandle — A titlebar area widget
Abstract Base Classes
GtkWidget — Base class for all widgets
GtkRange — Base class for widgets which visualize an adjustment
GtkIMContext — Base class for input method contexts
GtkNativeDialog — Integrate with native dialogs
GtkAccessible — Accessible interface
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
GtkEventControllerFocus — Event controller for focus
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
GtkShortcutController — Event controller for shortcuts
Keyboard shortcuts
Keyboard Accelerators — Utilities for accelerators
GtkShortcut — An object describing a keyboard shortcut
GtkShortcutTrigger — Triggers to track if shortcuts should be activated
GtkShortcutAction — Tracking if shortcuts should be activated
GtkShortcutManager — Interface for managing shortcuts
Data exchange, clipboards and Drag-and-Drop
GtkDragSource — Event controller to initiate DND operations
GtkDragIcon — A toplevel to use as drag icon
GtkDropTarget — Event controller to receive DND drops
GtkDropTargetAsync — Event controller to receive DND drops
GtkDropControllerMotion — Event controller for motion events during a drop
IV. GTK Core Reference
Initialization — Library initialization and main loop
Version Information — Variables and functions to check the GTK version
Settings — Sharing settings between applications
Standard Enumerations — Public enumerated types used throughout GTK
Testing — Utilities for testing GTK applications
Filesystem utilities — Functions for working with GIO
V. Theming in GTK
CSS nodes
The CSS nodes of a GtkScale
GTK CSS Selectors
GTK CSS Properties
Basic types
GTK CSS Properties
GtkStyleContext — Rendering UI elements
GtkCssProvider — CSS-like styling for widgets
GtkStyleProvider — Interface to provide style information to GtkStyleContext
GtkIconTheme — Looking up icons by name
VI. 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 GTK-specific command line arguments
Do not use widget style properties
Review your window creation flags
Stop using direct access to GdkEvent structs
Stop using gdk_pointer_warp()
Stop using non-RGBA visuals
Stop using GtkBox padding, fill and expand child properties
Stop using the state argument of GtkStyleContext getters
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()
Stop using GtkWidget event signals
Set a proper application ID
Stop using gtk_main() and related APIs
Reduce the use of gtk_widget_destroy()
Reduce the use of generic container APIs
Review your use of icon resources
Changes that need to be done at the time of the switch
Larger changes
Stop using GdkScreen
Stop using the root window
Stop using GdkVisual
Stop using GdkDeviceManager
Adapt to GdkWindow API changes
The iconified window state has been renamed to minimized
Adapt to GdkEvent API changes
Stop using grabs
Adapt to coordinate API changes
Adapt to GdkKeymap API changes
Adapt to changes in keyboard modifier handling
Stop using gtk_get_current_… APIs
Convert your ui files
Adapt to event controller API changes
Focus handling changes
Use the new apis for keyboard shortcuts
Stop using GtkEventBox
Stop using GtkButtonBox
Adapt to GtkBox API changes
Adapt to GtkWindow API changes
Adapt to GtkHeaderBar and GtkActionBar API changes
Adapt to GtkStack, GtkAssistant and GtkNotebook API changes
Adapt to button class hierarchy changes
Adapt to GtkScrolledWindow API changes
Adapt to GtkBin removal
Adapt to GtkContainer removal
Stop using GtkContainer::border-width
Adapt to gtk_widget_destroy() removal
Adapt to coordinate API changes
Adapt to GtkStyleContext API changes
Adapt to GtkCssProvider API changes
Stop using GtkShadowType and GtkRelief properties
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
Don’t use -gtk-icon-theme in your CSS
Don’t use -gtk-outline-…-radius in your CSS
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
Monitor handling has changed
Adapt to monitor API changes
Adapt to cursor API changes
Adapt to icon size API changes
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
Adapt to GtkScale changes
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
GtkEntryBuffer ::deleted-text has changed
GtkMenu, GtkMenuBar and GtkMenuItem are gone
GtkToolbar has been removed
GtkAspectFrame is no longer a frame
Stop using custom tooltip windows
Switch to the new Drag-and-Drop api
Adapt to GtkIconTheme API changes
Update to GtkFileChooser API changes
Stop using blocking dialog functions
Stop using GtkBuildable API
Adapt to GtkAboutDialog API changes
Adapt to GtkTreeView and GtkIconView tooltip context changes
Stop using GtkFileChooserButton
Changes to consider after the switch
Consider porting to the new list widgets
VII. 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
VIII. GTK Platform Support
Compiling the GTK Libraries
Building GTK
Build types
Debug builds
Release builds
Building and testing GTK
Extra Configuration Options
x11-backend, win32-backend, broadway-backend, wayland-backend and macos-backend
gtk_doc and man-pages
build-tests, install-tests, demos
Compiling GTK Applications on UNIX
Running and debugging GTK Applications
Environment variables
Interactive debugging
GTK for the X Window System
X11-specific environment variables
Understanding the X11 architecture
Server, client, window manager
Using GTK on Windows
Windows-specific environment variables
Windows-specific handling of cursors
Using GTK on Apple macOS
Using GTK with Broadway
Broadway-specific environment variables
Using GTK with Wayland
Wayland-specific environment variables
Index of all symbols
Annotation Glossary

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.