CTK+ 3 Reference Manual: CTK+ 3 Reference Manual

This document is for the CTK+ 3 library, version 3.25.7 . The latest versions can be found online at https://developer.gnome.org/ctk3/. If you are looking for the older CTK+ 2 series of libraries, see https://developer.gnome.org/ctk2/.

Mailing lists and bug reports — Getting help with CTK+

Common Questions — Find answers to common questions in the CTK+ manual

The CTK+ Drawing Model — The CTK+ drawing model in detail

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

II. CTK+ Widgets and Objects

Object Hierarchy

Widget Gallery

Application support

CtkApplication — Application class
CtkApplicationWindow — CtkWindow subclass with CtkApplication support
CtkActionable — An interface for widgets that can be associated with actions

Interface builder

CtkBuilder — Build an interface from an XML UI definition
CtkBuildable — Interface for objects that can be built by CtkBuilder

Windows

CtkWindow — Toplevel which can contain other widgets
CtkDialog — Create popup windows
CtkMessageDialog — A convenient message window
CtkAboutDialog — Display information about an application
CtkAssistant — A widget used to guide users through multi-step operations
CtkInvisible — A widget which is not displayed
CtkOffscreenWindow — A toplevel to manage offscreen rendering of child widgets
CtkWindowGroup — Limit the effect of grabs

Layout Containers

CtkBox — A container for packing widgets in a single row or column
CtkGrid — Pack widgets in rows and columns
CtkRevealer — Hide and show with animation
CtkListBox — A list container
CtkFlowBox — A container that allows reflowing its children
CtkStack — A stacking container
CtkStackSwitcher — A controller for CtkStack
CtkStackSidebar — An automatic sidebar widget
CtkActionBar — A full width bar for presenting contextual actions
CtkHeaderBar — A box with a centered child
CtkOverlay — A container which overlays widgets on top of each other
CtkButtonBox — A container for arranging buttons
CtkPaned — A widget with two adjustable panes
CtkLayout — Infinite scrollable area containing child widgets and/or custom drawing
CtkNotebook — A tabbed notebook container
CtkExpander — A container which can hide its child
CtkOrientable — An interface for flippable widgets
CtkAspectFrame — A frame that constrains its child to a particular aspect ratio
CtkFixed — A container which allows you to position widgets at fixed coordinates

Display Widgets

CtkLabel — A widget that displays a small to medium amount of text
CtkImage — A widget displaying an image
CtkSpinner — Show a spinner animation
CtkInfoBar — Report important messages to the user
CtkProgressBar — A widget which indicates progress visually
CtkLevelBar — A bar that can used as a level indicator
CtkStatusbar — Report messages of minor importance to the user
CtkAccelLabel — A label which displays an accelerator key on the right of the text

Buttons and Toggles

CtkButton — A widget that emits a signal when clicked on
CtkCheckButton — Create widgets with a discrete toggle button
CtkRadioButton — A choice from multiple check buttons
CtkToggleButton — Create buttons which retain their state
CtkLinkButton — Create buttons bound to a URL
CtkMenuButton — A widget that shows a popup when clicked on
CtkSwitch — A “light switch” style toggle
CtkScaleButton — A button which pops up a scale
CtkVolumeButton — A button which pops up a volume control
CtkLockButton — A widget to unlock or lock privileged operations
CtkModelButton — A button that uses a GAction as model

Numeric and Text Data Entry

CtkEntry — A single line text entry field
CtkEntryBuffer — Text buffer for CtkEntry
CtkEntryCompletion — Completion functionality for CtkEntry
CtkScale — A slider widget for selecting a value from a range
CtkSpinButton — Retrieve an integer or floating-point number from the user
CtkSearchEntry — An entry which shows a search icon
CtkSearchBar — A toolbar to integrate a search entry with
CtkEditable — Interface for text-editing widgets

Multiline Text Editor

Text Widget Overview — Overview of CtkTextBuffer, CtkTextView, and friends
CtkTextIter — Text buffer iterator
CtkTextMark — A position in the buffer preserved across buffer modifications
CtkTextBuffer — Stores attributed text for display in a CtkTextView
CtkTextTag — A tag that can be applied to text in a CtkTextBuffer
CtkTextTagTable — Collection of tags that can be used together
CtkTextView — Widget that displays a CtkTextBuffer

Tree, List and Icon Grid Widgets

Tree and List Widget Overview — Overview of CtkTreeModel, CtkTreeView, and friends
CtkTreeModel — The tree interface used by CtkTreeView
CtkTreeSelection — The selection object for CtkTreeView
CtkTreeViewColumn — A visible column in a CtkTreeView widget
CtkTreeView — A widget for displaying both trees and lists
CtkTreeView drag-and-drop — Interfaces for drag-and-drop support in CtkTreeView
CtkCellView — A widget displaying a single row of a CtkTreeModel
CtkIconView — A widget which displays a list of icons in a grid
CtkTreeSortable — The interface for sortable models used by CtkTreeView
CtkTreeModelSort — A CtkTreeModel which makes an underlying tree model sortable
CtkTreeModelFilter — A CtkTreeModel which hides parts of an underlying tree model
CtkCellLayout — An interface for packing cells
CtkCellArea — An abstract class for laying out CtkCellRenderers
CtkCellAreaBox — A cell area that renders CtkCellRenderers into a row or a column
CtkCellAreaContext — Stores geometrical information for a series of rows in a CtkCellArea
CtkCellRenderer — An object for rendering a single cell
CtkCellEditable — Interface for widgets that can be used for editing cells
CtkCellRendererAccel — Renders a keyboard accelerator in a cell
CtkCellRendererCombo — Renders a combobox in a cell
CtkCellRendererPixbuf — Renders a pixbuf in a cell
CtkCellRendererProgress — Renders numbers as progress bars
CtkCellRendererSpin — Renders a spin button in a cell
CtkCellRendererText — Renders text in a cell
CtkCellRendererToggle — Renders a toggle button in a cell
CtkCellRendererSpinner — Renders a spinning animation in a cell
CtkListStore — A list-like data structure that can be used with the CtkTreeView
CtkTreeStore — A tree-like data structure that can be used with the CtkTreeView

Menus, Combo Box, Toolbar

CtkComboBox — A widget used to choose from a list of items
CtkComboBoxText — A simple, text-only combo box
CtkMenu — A menu widget
CtkMenuBar — A subclass of CtkMenuShell which holds CtkMenuItem widgets
CtkMenuItem — The widget used for item in menus
CtkRadioMenuItem — A choice from multiple check menu items
CtkCheckMenuItem — A menu item with a check box
CtkSeparatorMenuItem — A separator used in menus
CtkToolShell — Interface for containers containing CtkToolItem widgets
CtkToolbar — Create bars of buttons and other widgets
CtkToolItem — The base class of widgets that can be added to CtkToolShell
CtkToolPalette — A tool palette with categories
CtkToolItemGroup — A sub container used in a tool palette
CtkSeparatorToolItem — A toolbar item that separates groups of other toolbar items
CtkToolButton — A CtkToolItem subclass that displays buttons
CtkMenuToolButton — A CtkToolItem containing a button with an additional dropdown menu
CtkToggleToolButton — A CtkToolItem containing a toggle button
CtkRadioToolButton — A toolbar item that contains a radio button
CtkPopover — Context dependent bubbles
CtkPopoverMenu — Popovers to use as menus

Selector Widgets and Dialogs

CtkColorChooser — Interface implemented by widgets for choosing colors
CtkColorButton — A button to launch a color selection dialog
CtkColorChooserWidget — A widget for choosing colors
CtkColorChooserDialog — A dialog for choosing colors
CtkFileChooser — File chooser interface used by CtkFileChooserWidget and CtkFileChooserDialog
CtkFileChooserButton — A button to launch a file selection dialog
CtkFileChooserNative — A native file chooser dialog, suitable for “File/Open” or “File/Save” commands
CtkFileChooserDialog — A file chooser dialog, suitable for “File/Open” or “File/Save” commands
CtkFileChooserWidget — A file chooser widget
CtkFileFilter — A filter for selecting a file subset
CtkFontChooser — Interface implemented by widgets displaying fonts
CtkFontButton — A button to launch a font chooser dialog
CtkFontChooserWidget — A widget for selecting fonts
CtkFontChooserDialog — A dialog for selecting fonts
CtkPlacesSidebar — Sidebar that displays frequently-used places in the file system

Ornaments

CtkFrame — A bin with a decorative frame and optional label
CtkSeparator — A separator widget

Scrolling

CtkScrollbar — A Scrollbar
CtkScrolledWindow — Adds scrollbars to its child widget
CtkScrollable — An interface for scrollable widgets

Printing

CtkPrintOperation — High-level Printing API
CtkPrintContext — Encapsulates context for drawing pages
CtkPrintSettings — Stores print settings
CtkPageSetup — Stores page setup information
CtkPaperSize — Support for named paper sizes
CtkPrinter — Represents a printer
CtkPrintJob — Represents a print job
CtkPrintUnixDialog — A print dialog
CtkPageSetupUnixDialog — A page setup dialog

Shortcuts Overview

CtkShortcutsWindow — Toplevel which shows help for shortcuts
CtkShortcutsSection — Represents an application mode in a CtkShortcutsWindow
CtkShortcutsGroup — Represents a group of shortcuts in a CtkShortcutsWindow
CtkShortcutsShortcut — Represents a keyboard shortcut in a CtkShortcutsWindow

Miscellaneous

CtkAdjustment — A representation of an adjustable bounded value
CtkCalendar — Displays a calendar and allows the user to select a date
CtkDrawingArea — A widget for custom user interface elements
CtkGLArea — A widget for custom drawing with OpenGL
CtkEventBox — A widget used to catch events for widgets which do not have their own window
CtkHandleBox — a widget for detachable window portions
CtkIMContextSimple — An input method context supporting table-based input methods
CtkIMMulticontext — An input method context supporting multiple, loadable input methods
CtkSizeGroup — Grouping widgets so they request the same size
CtkTooltip — Add tips to your widgets
CtkViewport — An adapter which makes widgets scrollable
CtkAccessible — Accessibility support for widgets

Abstract Base Classes

CtkWidget — Base class for all widgets
CtkContainer — Base class for widgets which contain other widgets
CtkBin — A container with just one child
CtkMenuShell — A base class for menu objects
CtkRange — Base class for widgets which visualize an adjustment
CtkIMContext — Base class for input method contexts
CtkNativeDialog — Integrate with native dialogs

Cross-process Embedding

CtkPlug — Toplevel for embedding into other processes
CtkSocket — Container for widgets from other processes

Recently Used Documents

CtkRecentManager — Managing recently used files
CtkRecentChooser — Interface implemented by widgets displaying recently used files
CtkRecentChooserDialog — Displays recently used files in a dialog
CtkRecentChooserMenu — Displays recently used files in a menu
CtkRecentChooserWidget — Displays recently used files
CtkRecentFilter — A filter for selecting a subset of recently used files

Choosing from installed applications

CtkAppChooser — Interface implemented by widgets for choosing an application
CtkAppChooserButton — A button to launch an application chooser dialog
CtkAppChooserDialog — An application chooser dialog
CtkAppChooserWidget — Application chooser widget that can be embedded in other widgets

Gestures and event handling

CtkEventController — Self-contained handler of series of events
CtkEventControllerKey — Event controller for key events
CtkEventControllerScroll — Event controller for scroll events
CtkEventControllerMotion — Event controller for motion events
CtkGesture — Base class for gestures
CtkGestureSingle — Base class for mouse/single-touch gestures
CtkGestureDrag — Drag gesture
CtkGestureLongPress — "Press and Hold" gesture
CtkGestureMultiPress — Multipress gesture
CtkGesturePan — Pan gesture
CtkGestureSwipe — Swipe gesture
CtkGestureRotate — Rotate gesture
CtkGestureZoom — Zoom gesture
CtkGestureStylus — Gesture for stylus input
CtkPadController — Controller for drawing tablet pads

Deprecated

CtkSymbolicColor — Symbolic colors
CtkGradient — Gradients
Resource Files — Routines for handling resource files
CtkStyle — Object that holds style information for widgets
CtkHScale — A horizontal slider widget for selecting a value from a range
CtkVScale — A vertical slider widget for selecting a value from a range
CtkTearoffMenuItem — A menu item used to tear off and reattach its menu
CtkColorSelection — Widget used to select a color
CtkColorSelectionDialog — Dialog box for selecting a color
CtkHSV — A “color wheel” widget
CtkFontSelection — Deprecated widget for selecting fonts
CtkFontSelectionDialog — Deprecated dialog box for selecting fonts
CtkHBox — A horizontal container box
CtkVBox — A vertical container box
CtkHButtonBox — A container for arranging buttons horizontally
CtkVButtonBox — A container for arranging buttons vertically
CtkHPaned — A container with two panes arranged horizontally
CtkVPaned — A container with two panes arranged vertically
CtkTable — Pack widgets in regular patterns
CtkHSeparator — A horizontal separator
CtkVSeparator — A vertical separator
CtkHScrollbar — A horizontal scrollbar
CtkVScrollbar — A vertical scrollbar
CtkUIManager — Constructing menus and toolbars from an XML description
CtkActionGroup — A group of actions
CtkAction — An action which can be triggered by a menu or toolbar item
CtkToggleAction — An action which can be toggled between two states
CtkRadioAction — An action of which only one in a group can be active
CtkRecentAction — An action of which represents a list of recently used files
CtkActivatable — An interface for activatable widgets
CtkImageMenuItem — Widget for a menu item with an icon
CtkMisc — Base class for widgets with alignments and padding
Stock Items — Prebuilt common menu/toolbar items and corresponding icons
Themeable Stock Images — Manipulating stock icons
CtkNumerableIcon — A GIcon that allows numbered emblems
CtkArrow — Displays an arrow
CtkStatusIcon — Display an icon in the system tray
CtkThemingEngine — Theming renderers
CtkAlignment — A widget which controls the alignment and size of its child

III. CTK+ Core Reference

Main loop and Events — Library initialization, main event loop, and events
Version Information — Variables and functions to check the CTK+ version
Accelerator Groups — Groups of global keyboard accelerators for an entire CtkWindow
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 CTK+
Selections — Functions for handling inter-process communication via selections
Testing — Utilities for testing CTK+ applications
Filesystem utilities — Functions for working with GIO

IV. Theming in CTK+

CTK+ CSS Overview — Overview of CSS in CTK+
CTK+ CSS Properties — CSS Properties in CTK+
CtkStyleContext — Rendering UI elements
CtkCssProvider — CSS-like styling for widgets
CtkStyleProvider — Interface to provide style information to CtkStyleContext
CtkStyleProperties — Store for style property information
CtkWidgetPath — Widget path abstraction
CtkIconTheme — Looking up icons by name

V. Migrating from Previous Versions of CTK+

Migrating from CTK+ 2.x to CTK+ 3

Preparation in CTK+ 2.x

Do not include individual headers
Do not use deprecated symbols
Use accessor functions instead of direct access
Replace CDK_<keyname> with CDK_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 CdkRegion by cairo_region_t
Replace CdkPixmap by cairo surfaces
Replace CdkColormap by CdkVisual
CdkDrawable is gone
Event filtering
Backend-specific code
CtkPlug and CtkSocket
The CtkWidget::draw signal
CtkProgressBar orientation
Check your expand and fill flags
Scrolling changes
CtkObject is gone
CtkEntryCompletion signal parameters
Resize grips
Prevent mixed linkage
Install CTK+ 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 CtkApplication

Uniqueness
Commands and Messages

Migrating from EggSMClient to CtkApplication

Migrating from other containers to CtkGrid

CtkBox versus CtkGrid: packing
CtkBox versus CtkGrid: sizing
CtkBox versus CtkGrid: spacing

Migration Details Checklist

Implement CtkWidget::popup_menu
Use CdkEventExpose.region
Test for modifier keys correctly
Use named icons

Migrating from one CTK+ 3 release to another

Changes in CTK+ 3.2
Changes in CTK+ 3.4
Changes in CTK+ 3.6
Changes in CTK+ 3.8
Changes in CTK+ 3.10
Changes in CTK+ 3.12
Changes in CTK+ 3.14
Changes in CTK+ 3.16
Changes in CTK+ 3.18
Changes in CTK+ 3.20
Changes in CTK+ 3.22

VI. CTK+ Tools

ctk3-demo — Demonstrate CTK+ widgets
ctk3-demo-application — Demonstrate CtkApplication
ctk3-widget-factory — Demonstrate CTK+ widgets
ctk3-icon-browser — List themed icons
ctk-query-immodules-3.0 — Input method module registration utility
ctk-update-icon-cache — Icon theme caching utility
ctk-encode-symbolic-svg — Symbolic icon conversion utility
ctk-builder-tool — CtkBuilder file utility
ctk-launch — Launch an application
ctk-query-settings — Utility to print name and value of all CtkSettings properties
cdkbroadwayd — Broadway display server

VII. CTK+ Platform Support

Compiling the CTK+ libraries — How to compile CTK+ itself
Compiling CTK+ Applications — How to compile your CTK+ application
Running CTK+ Applications — How to run and debug your CTK+ application
Using CTK+ on the X Window System — X11-specific aspects of using CTK+
Using CTK+ on Windows — Windows-specific aspects of using CTK+
Using CTK+ on Mac OS X — OS X-specific aspects of using CTK+
Using CTK+ with Broadway — HTML-specific aspects of using CTK+
Using CTK+ with Wayland — Wayland-specific aspects of using CTK+

Glossary

Index of all symbols

Annotation Glossary