GTK+ 3 Reference Manual: GTK+ 3 Reference Manual

This document is for the GTK+ 3 library, version 3.20.8 . The latest versions can be found online at http://developer.gnome.org/gtk3/. If you are looking for the older GTK+ 2 series of libraries, see http://developer.gnome.org/gtk2/.

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
Properties
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 — The GTK+ drawing model in detail

The GTK+ Input and Event Handling Model — GTK+ input and event handling in detail

II. GTK+ Widgets and Objects

Object Hierarchy

Widget Gallery

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

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
GtkInvisible — A widget which is not displayed
GtkOffscreenWindow — A toplevel to manage offscreen rendering of child widgets
GtkWindowGroup — Limit the effect of grabs

Layout Containers

GtkBox — A container box
GtkGrid — Pack widgets in a 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
GtkButtonBox — A container for arranging buttons
GtkPaned — A widget with two adjustable panes
GtkLayout — Infinite scrollable area containing child widgets and/or custom drawing
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

Display Widgets

GtkLabel — A widget that displays a small to medium amount of text
GtkImage — A widget displaying an image
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

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

GtkEntry — A single line text entry field
GtkEntryBuffer — Text buffer for GtkEntry
GtkEntryCompletion — Completion functionality for GtkEntry
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
GtkEditable — Interface for text-editing widgets

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 which can are 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
GtkToolPalette — A tool palette with categories
GtkToolItemGroup — A sub container used in a tool palette
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

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
GtkPlacesSidebar — Sidebar that displays frequently-used places in the file system

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

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

Miscellaneous

GtkAdjustment — A representation of an adjustable bounded value
GtkCalendar — Displays a calendar and allows the user to select a date
GtkDrawingArea — A widget for custom user interface elements
GtkGLArea — A widget for custom drawing with OpenGL
GtkEventBox — A widget used to catch events for widgets which do not have their own window
GtkHandleBox — a widget for detachable window portions
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
GtkTooltip — Add tips to your widgets
GtkViewport — An adapter which makes widgets scrollable
GtkAccessible — Accessibility support for widgets

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

Cross-process Embedding

GtkPlug — Toplevel for embedding into other processes
GtkSocket — Container for widgets from other processes

Recently Used Documents

GtkRecentManager — Managing recently used files
GtkRecentChooser — Interface implemented by widgets displaying recently used files
GtkRecentChooserDialog — Displays recently used files in a dialog
GtkRecentChooserMenu — Displays recently used files in a menu
GtkRecentChooserWidget — Displays recently used files
GtkRecentFilter — A filter for selecting a subset of 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

GtkEventController — Self-contained handler of series of events
GtkGesture — Base class for gestures
GtkGestureSingle — Base class for mouse/single-touch gestures
GtkGestureDrag — Drag gesture
GtkGestureLongPress — "Press and Hold" gesture
GtkGestureMultiPress — Multipress gesture
GtkGesturePan — Pan gesture
GtkGestureSwipe — Swipe gesture
GtkGestureRotate — Rotate gesture
GtkGestureZoom — Zoom gesture

GtkSymbolicColor — Symbolic colors
GtkGradient — Gradients
Resource Files — Deprecated routines for handling resource files
GtkStyle — Deprecated object that holds style information for widgets
GtkHScale — A horizontal slider widget for selecting a value from a range
GtkVScale — A vertical slider widget for selecting a value from a range
GtkTearoffMenuItem — A menu item used to tear off and reattach its menu
GtkColorSelection — Deprecated widget used to select a color
GtkColorSelectionDialog — Deprecated dialog box for selecting a color
GtkHSV — A “color wheel” widget
GtkFontSelection — Deprecated widget for selecting fonts
GtkFontSelectionDialog — Deprecated dialog box for selecting fonts
GtkHBox — A horizontal container box
GtkVBox — A vertical container box
GtkHButtonBox — A container for arranging buttons horizontally
GtkVButtonBox — A container for arranging buttons vertically
GtkHPaned — A container with two panes arranged horizontally
GtkVPaned — A container with two panes arranged vertically
GtkTable — Pack widgets in regular patterns
GtkHSeparator — A horizontal separator
GtkVSeparator — A vertical separator
GtkHScrollbar — A horizontal scrollbar
GtkVScrollbar — A vertical scrollbar
GtkUIManager — Constructing menus and toolbars from an XML description
GtkActionGroup — A group of actions
GtkAction — A deprecated action which can be triggered by a menu or toolbar item
GtkToggleAction — An action which can be toggled between two states
GtkRadioAction — An action of which only one in a group can be active
GtkRecentAction — An action of which represents a list of recently used files
GtkActivatable — An interface for activatable widgets
GtkImageMenuItem — A deprecated widget for a menu item with an icon
GtkMisc — Base class for widgets with alignments and padding
Stock Items — Prebuilt common menu/toolbar items and corresponding icons
Themeable Stock Images — Manipulating stock icons
GtkNumerableIcon — A GIcon that allows numbered emblems
GtkArrow — Displays an arrow
GtkStatusIcon — Display an icon in the system tray
GtkThemingEngine — Theming renderers
GtkAlignment — A widget which controls the alignment and size of its child

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
Clipboards — Storing data on clipboards
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 of CSS in GTK+
GTK+ CSS — GTK+ CSS Properties
GtkStyleContext — Rendering UI elements
GtkCssProvider — CSS-like styling for widgets
GtkStyleProvider — Interface to provide style information to GtkStyleContext
GtkStyleProperties — Store for style property information
GtkWidgetPath — Widget path abstraction
GtkIconTheme — Looking up icons by name

V. Migrating from Previous Versions of GTK+

Migrating from GTK+ 2.x to GTK+ 3

Preparation in GTK+ 2.x

Do not include individual headers
Do not use deprecated symbols
Use accessor functions instead of direct access
Replace GDK_<keyname> with GDK_KEY_<keyname>
Use GIO for launching applications
Use cairo for drawing

Changes that need to be done at the time of the switch

Replace size_request by get_preferred_width/height
Replace GdkRegion by cairo_region_t
Replace GdkPixmap by cairo surfaces
Replace GdkColormap by GdkVisual
GdkDrawable is gone
Event filtering
Backend-specific code
GtkPlug and GtkSocket
The GtkWidget::draw signal
GtkProgressBar orientation
Check your expand and fill flags
Scrolling changes
GtkObject is gone
GtkEntryCompletion signal parameters
Resize grips
Prevent mixed linkage
Install GTK+ modules in the right place

Theming changes

Migrating themes
Migrating theme engines
Extending the CSS parser
Using the CSS file format
A checklist for widgets
Parsing of custom resources
Bonus points

Migrating from libunique to GApplication or GtkApplication

Uniqueness
Commands and Messages

Migrating from EggSMClient to GtkApplication

Migrating from other containers to GtkGrid

GtkBox versus GtkGrid: packing
GtkBox versus GtkGrid: sizing
GtkBox versus GtkGrid: spacing

Migration Details Checklist

Implement GtkWidget::popup_menu
Use GdkEventExpose.region
Test for modifier keys correctly
Use named icons

VI. GTK+ Tools

gtk3-demo — Demonstrate GTK+ widgets
gtk3-demo-application — Demonstrate GtkApplication
gtk3-widget-factory — Demonstrate GTK+ widgets
gtk3-icon-browser — List themed icons
gtk-query-immodules-3.0 — Input method module registration utility
gtk-update-icon-cache — Icon theme caching utility
gtk-encode-symbolic-svg — Symbolic icon conversion utility
gtk-builder-tool — GtkBuilder file utility
gtk-launch — Launch an application
gtk-query-settings — Utility to print name and value of all GtkSettings properties
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 Mac OS X — OS X-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+
Using GTK+ with Mir — Mir-specific aspects of using GTK+

Index of all symbols

Index of deprecated symbols

Index of new symbols in 3.0

Index of new symbols in 3.2

Index of new symbols in 3.4

Index of new symbols in 3.6

Index of new symbols in 3.8

Index of new symbols in 3.10

Index of new symbols in 3.12

Index of new symbols in 3.14

Index of new symbols in 3.16

Index of new symbols in 3.18

Index of new symbols in 3.20

Annotation Glossary