GTK 4 Reference Manual
This document is for the GTK 4 library, version 4.0.3 . The latest versions can be found online at https://developer.gnome.org/gtk4/. If you are looking for the older GTK 3 series of libraries, see https://developer.gnome.org/gtk3/.
- I. Introduction
- II. GTK Concepts
- 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
- 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
- Windows
-
- 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
- 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
- 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
- Ornaments
-
- GtkFrame — A widget with a decorative frame and optional label
- GtkSeparator — A separator widget
- Scrolling
-
- GtkScrollbar — A Scrollbar
- GtkScrolledWindow — Adds scrollbars to its child widget
- GtkScrollable — An interface for scrollable widgets
- GtkViewport — An adapter which makes widgets scrollable
- Printing
-
- 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
- Accessibility
-
- GTK Accessibility
- GtkAccessible — Accessible interface
- GtkATContext — An object communicating to Assistive Technologies
- Miscellaneous
-
- 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 in GTK
- 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()andgdk_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
- Replace GtkClipboard with GdkClipboard
-
Stop using
gtk_get_current_...APIs - Convert your ui files
- Adapt to GtkBuilder API changes
- 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 using
gtk_widget_grab_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
- Adapt to changed GtkSettings properties
- Changes to consider after the switch
- 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
- Compiling GTK Applications on UNIX
- Running and debugging GTK Applications
- GTK for the X Window System
- Using GTK on Windows
- Using GTK on Apple macOS
- Using GTK with Broadway
- Using GTK with Wayland
- Index of all symbols
- Annotation Glossary
© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer-old.gnome.org/gtk4/4.0/index.html