gem-graph/gem-graph-client
gem-graph
/
gem-graph-client
3
0
Fork 0
Code Issues 14 Pull Requests Projects Releases Activity
gem-graph-client/docs/GTK-docs/gnome-dev-documentation/developer.gnome.org/documentation/tutorials/widget-templates.html

511 lines
40 KiB
HTML
Raw Normal View History

docs/*: integrate doxygen, create a documentation zone, adds notes We wanted to have an automated documentation for our project. We choose doxygen since this is a well-established project, with common standards. To generate the documentation, simply type `make docs` and open `docs/html/index.html`. The documentation zone actually contains: - archives: several files from past of the projects, historical purpose - GTK-docs: ressources on GTK internals and API - rtfm: first draft of a user manual - showcase: some pictures of the UI example, that were communicated on the Gem-graph discussion room (XMPP) - html: doxygen-generated docs
2024-10-28 13:57:44 +01:00
<!doctype html>
<html class="no-js">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="prev" title="Drag and Drop" href="drag-and-drop.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2022.06.21"/>
<title>Widget Templates - GNOME Developer Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?digest=40978830699223671f4072448e654b5958f38b89" />
<link rel="stylesheet" type="text/css" href="../_static/tabs.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
<link rel="stylesheet" type="text/css" href="../_static/gnome.css" />
<style>
body {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-half" viewBox="0 0 24 24">
<title>Auto light/dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
<circle cx="12" cy="12" r="9" />
<path d="M13 12h5" />
<path d="M13 15h4" />
<path d="M13 18h1" />
<path d="M13 9h4" />
<path d="M13 6h1" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../index.html"><div class="brand">GNOME Developer Documentation</div></a>
</div>
<div class="header-right">
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
<span class="sidebar-brand-text">GNOME Developer Documentation</span>
</a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
<input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 has-children"><a class="reference internal" href="../introduction.html">Platform Introduction</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../introduction/components.html">Platform Components</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../introduction/overview/libraries.html">Libraries</a></li>
<li class="toctree-l3"><a class="reference internal" href="../introduction/overview/services.html">Services</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/languages.html">Programming Languages</a></li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/builder.html">GNOME Builder</a></li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/flatpak.html">Flatpak</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../guidelines.html">Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../guidelines/programming.html">Programming Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/coding-style.html">C Coding Style</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/memory-management.html">Managing Memory</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/writing-good-code.html">The Importance of Writing Good Code</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/optimizing.html">Optimizing GNOME Applications</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/namespacing.html">Namespacing</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/programming/introspection.html">Introspection</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../guidelines/accessibility.html">Accessibility</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/accessibility/coding-guidelines.html">Coding Guidelines for Supporting Accessibility</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/accessibility/custom-widgets.html">Making Custom Components Accessible</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../guidelines/localization.html">Localization</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/localization/practices.html">Best Practices for Localization</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../guidelines/maintainer.html">Maintainer Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/maintainer/api-stability.html">API Stability</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/maintainer/parallel-installability.html">Parallel Installability</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidelines/maintainer/integrating.html">Integrating with GNOME</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../guidelines/devel-docs.html">Developer Documentation Style Guidelines</a></li>
</ul>
</li>
<li class="toctree-l1 current has-children"><a class="reference internal" href="../tutorials.html">Tutorials</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2 has-children"><a class="reference internal" href="beginners.html">Beginners Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3 has-children"><a class="reference internal" href="beginners/getting_started.html">Getting Started</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/content_view.html">Adding A Content View</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/opening_files.html">Loading Content From A File</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/cursor_position.html">Showing The Cursor Position</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/saving_files.html">Saving The Content To A File</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/saving_state.html">Saving The Application State</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/adding_toasts.html">Notifying The User With Toasts</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/getting_started/dark_mode.html">Forcing The Dark Color Scheme</a></li>
</ul>
</li>
<li class="toctree-l3 has-children"><a class="reference internal" href="beginners/components.html">UI components</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/window.html">Windows</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/image.html">Images</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/label.html">Labels</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/button.html">Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/box.html">Boxes</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/stack.html">Stacks</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/leaflet.html">Leaflets</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/toggle.html">Toggles</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/check_box.html">Check Boxes</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/radio_button.html">Radio Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/spin_button.html">Spin Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/link_button.html">Link Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/switch.html">Switches</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/menu_button.html">Menu Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/entry.html">Entries</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/password_entry.html">Password Entries</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/message_dialog.html">Messages</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/file_dialog.html">File Dialogs</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/spinner.html">Spinners</a></li>
<li class="toctree-l4"><a class="reference internal" href="beginners/components/level_bar.html">Level Bars</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="application-id.html">Application ID</a></li>
<li class="toctree-l2"><a class="reference internal" href="application.html">Using GtkApplication</a></li>
<li class="toctree-l2"><a class="reference internal" href="save-state.html">Saving and Loading Window State</a></li>
<li class="toctree-l2"><a class="reference internal" href="notifications.html">Using Notifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="themed-icons.html">Themed Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="deprecations.html">Dealing With Deprecations</a></li>
<li class="toctree-l2"><a class="reference internal" href="actions.html">Actions</a></li>
<li class="toctree-l2"><a class="reference internal" href="menus.html">Menus</a></li>
<li class="toctree-l2"><a class="reference internal" href="search-provider.html">Writing a Search Provider</a></li>
<li class="toctree-l2"><a class="reference internal" href="pre-and-post-conditions.html">Pre- and Post-Conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="main-contexts.html">Main Contexts</a></li>
<li class="toctree-l2"><a class="reference internal" href="lists.html">Using GLib Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="threading.html">Threading</a></li>
<li class="toctree-l2"><a class="reference internal" href="asynchronous-programming.html">Asynchronous Programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="drag-and-drop.html">Drag and Drop</a></li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Widget Templates</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<main class="main">
<div class="content">
<article role="main">
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
<section id="widget-templates">
<h1>Widget Templates<a class="headerlink" href="#widget-templates" title="Permalink to this headline">#</a></h1>
<p>GTK provides a way to describe UIs using definition files and the
<a class="reference external" href="https://docs.gtk.org/gtk4/class.Builder.html">GtkBuilder</a> API. Typically
you will need to create a <code class="docutils literal notranslate"><span class="pre">GtkBuilder</span></code> object instance and load the UI
definition XML file, extract the generated objects, and store references to
them inside your own types and data structures.</p>
<p>To automate this work, GTK also provides <em>templates</em>: a way to automatically
load the UI definition of a GTK widget type, bind the objects described in the
XML to fields in the widget instance, and automatically manage their lifetime.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>UI definitions can describe any object type that inherits from GObject.
Only widgets can have templates, but templates can contain any object.</p>
</div>
<section id="using-a-template">
<h2>Using a template<a class="headerlink" href="#using-a-template" title="Permalink to this headline">#</a></h2>
<p>Templates are bound to a type, and are loaded whenever a new instance of that
type is created.</p>
<p>In order to use a template you will need to register it at class initialization
time. Typically you will have your UI definition file bundled with your binary
using <a class="reference external" href="https://docs.gtk.org/gio/struct.Resource.html">GResource</a>, in order
to reliably access it from your project.</p>
<p>As an example, we have a composite widget type that contains two children:</p>
<ul class="simple">
<li><p>an entry</p></li>
<li><p>a button</p></li>
</ul>
<p>Its UI definition file is going to be:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;interface&gt;</span>
<span class="nt">&lt;template</span> <span class="na">class=</span><span class="s">&quot;ExampleWidget&quot;</span> <span class="na">parent=</span><span class="s">&quot;GtkWidget&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkEntry&quot;</span> <span class="na">id=</span><span class="s">&quot;entry&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;/object&gt;</span>
<span class="nt">&lt;/child&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkButton&quot;</span> <span class="na">id=</span><span class="s">&quot;button&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;label&quot;</span><span class="nt">&gt;</span>Hello<span class="nt">&lt;/property&gt;</span>
<span class="nt">&lt;/object&gt;</span>
<span class="nt">&lt;/child&gt;</span>
<span class="nt">&lt;/template&gt;</span>
<span class="nt">&lt;/interface&gt;</span>
</pre></div>
</div>
<p>and it is going to be saved as a <code class="docutils literal notranslate"><span class="pre">GResource</span></code> under the <code class="docutils literal notranslate"><span class="pre">/com/example/widget.ui</span></code>
path.</p>
<div class="sphinx-tabs docutils container">
<div aria-label="Tabbed content" class="closeable" role="tablist"><button aria-controls="panel-0-0-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-0-0-0" name="0-0" role="tab" tabindex="0">C</button></div><div aria-labelledby="tab-0-0-0" class="sphinx-tabs-panel" id="panel-0-0-0" name="0-0" role="tabpanel" tabindex="0"><ol class="arabic simple">
<li><p>Add the template registration to your <code class="docutils literal notranslate"><span class="pre">class_init</span></code> function</p></li>
</ol>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">G_DECLARE_FINAL_TYPE</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">example_widget</span><span class="p">,</span><span class="w"> </span><span class="n">EXAMPLE</span><span class="p">,</span><span class="w"> </span><span class="n">WIDGET</span><span class="p">,</span><span class="w"> </span><span class="n">GtkWidget</span><span class="p">)</span><span class="w"></span>
<span class="k">struct</span><span class="w"> </span><span class="nc">_ExampleWidget</span><span class="w"></span>
<span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">GtkWidget</span><span class="w"> </span><span class="n">parent_type</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">GtkWidget</span><span class="w"> </span><span class="o">*</span><span class="n">entry</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">GtkWidget</span><span class="w"> </span><span class="o">*</span><span class="n">button</span><span class="p">;</span><span class="w"></span>
<span class="p">};</span><span class="w"></span>
<span class="n">G_DEFINE_TYPE</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">example_widget</span><span class="p">,</span><span class="w"> </span><span class="n">GTK_TYPE_WIDGET</span><span class="p">)</span><span class="w"></span>
<span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"></span>
<span class="n">example_widget_class_init</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">klass</span><span class="p">)</span><span class="w"></span>
<span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">GtkWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">widget_class</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GTK_WIDGET_CLASS</span><span class="w"> </span><span class="p">(</span><span class="n">klass</span><span class="p">);</span><span class="w"></span>
<span class="hll"><span class="w"> </span><span class="n">gtk_widget_class_set_template_from_resource</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"></span>
</span><span class="hll"><span class="w"> </span><span class="s">&quot;/com/example/widget.ui&quot;</span><span class="p">);</span><span class="w"></span>
</span><span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ol class="arabic simple" start="2">
<li><p>Bind the widgets defined inside the template file to the corresponding
members of the widget’s instance data structure</p></li>
</ol>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"></span>
<span class="nf">example_widget_class_init</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">klass</span><span class="p">)</span><span class="w"></span>
<span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">GtkWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">widget_class</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GTK_WIDGET_CLASS</span><span class="w"> </span><span class="p">(</span><span class="n">klass</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">gtk_widget_class_set_template_from_resource</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">&quot;/com/example/widget.ui&quot;</span><span class="p">);</span><span class="w"></span>
<span class="hll"><span class="w"> </span><span class="n">gtk_widget_class_bind_template_child</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"> </span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">entry</span><span class="p">);</span><span class="w"></span>
</span><span class="hll"><span class="w"> </span><span class="n">gtk_widget_class_bind_template_child</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"> </span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">button</span><span class="p">);</span><span class="w"></span>
</span><span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ol class="arabic simple" start="3">
<li><p>Initialize the template children when initializing the widgdet instance</p></li>
</ol>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"></span>
<span class="nf">example_widget_init</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidget</span><span class="w"> </span><span class="o">*</span><span class="n">self</span><span class="p">)</span><span class="w"></span>
<span class="p">{</span><span class="w"></span>
<span class="hll"><span class="w"> </span><span class="n">gtk_widget_init_template</span><span class="w"> </span><span class="p">(</span><span class="n">GTK_WIDGET</span><span class="w"> </span><span class="p">(</span><span class="n">self</span><span class="p">));</span><span class="w"></span>
</span>
<span class="w"> </span><span class="c1">// It is now possible to access self-&gt;entry and self-&gt;button</span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<ol class="arabic simple" start="4">
<li><p>Clear the template children when disposing the widget instance</p></li>
</ol>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"></span>
</span><span class="hll"><span class="nf">example_widget_dispose</span><span class="w"> </span><span class="p">(</span><span class="n">GObject</span><span class="w"> </span><span class="o">*</span><span class="n">gobject</span><span class="p">)</span><span class="w"></span>
</span><span class="hll"><span class="p">{</span><span class="w"></span>
</span><span class="hll"><span class="w"> </span><span class="n">gtk_widget_dispose_template</span><span class="w"> </span><span class="p">(</span><span class="n">GTK_WIDGET</span><span class="w"> </span><span class="p">(</span><span class="n">gobject</span><span class="p">),</span><span class="w"> </span><span class="n">EXAMPLE_TYPE_WIDGET</span><span class="p">);</span><span class="w"></span>
</span><span class="hll">
</span><span class="hll"><span class="w"> </span><span class="n">G_OBJECT_CLASS</span><span class="w"> </span><span class="p">(</span><span class="n">example_widget_parent_class</span><span class="p">)</span><span class="o">-&gt;</span><span class="n">dispose</span><span class="w"> </span><span class="p">(</span><span class="n">gobject</span><span class="p">);</span><span class="w"></span>
</span><span class="hll"><span class="p">}</span><span class="w"></span>
</span>
<span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"></span>
<span class="nf">example_widget_class_init</span><span class="w"> </span><span class="p">(</span><span class="n">ExampleWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">klass</span><span class="p">)</span><span class="w"></span>
<span class="p">{</span><span class="w"></span>
<span class="hll"><span class="w"> </span><span class="n">G_OBJECT_CLASS</span><span class="w"> </span><span class="p">(</span><span class="n">klass</span><span class="p">)</span><span class="o">-&gt;</span><span class="n">dispose</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">example_widget_dispose</span><span class="p">;</span><span class="w"></span>
</span>
<span class="w"> </span><span class="n">GtkWidgetClass</span><span class="w"> </span><span class="o">*</span><span class="n">widget_class</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GTK_WIDGET_CLASS</span><span class="w"> </span><span class="p">(</span><span class="n">klass</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">gtk_widget_class_set_template_from_resource</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">&quot;/com/example/widget.ui&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">gtk_widget_class_bind_template_child</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"> </span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">entry</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">gtk_widget_class_bind_template_child</span><span class="w"> </span><span class="p">(</span><span class="n">widget_class</span><span class="p">,</span><span class="w"> </span><span class="n">ExampleWidget</span><span class="p">,</span><span class="w"> </span><span class="n">button</span><span class="p">);</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
</div></div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is not necessary to bind all the template children defined in the UI
file. You can use <code class="docutils literal notranslate"><span class="pre">gtk_widget_get_template_child()</span></code> to access a named
template child at run time. If you find yourself accessing the same
template child multiple times, it is more efficient to store the reference
inside your instance data structure.</p>
</div>
</section>
<section id="when-to-use-templates">
<h2>When to use templates<a class="headerlink" href="#when-to-use-templates" title="Permalink to this headline">#</a></h2>
<p>Templates are useful as a way to keep code maintainable, and reduce the size
of UI definition files. If your UI definitions become increasingly complex or
include too many levels of nested widgets, then you should consider moving
blocks of functionality and related widgets into their own composite template,
and then instantiate the template widget from their parent’s UI definition. For
instance, given this UI definition:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStack&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStackPage&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;child&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;orientation&quot;</span><span class="nt">&gt;</span>vertical<span class="nt">&lt;/property&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkButton&quot;</span><span class="nt">&gt;</span>
<span class="cm">&lt;!-- ... --&gt;</span>
</pre></div>
</div>
<p>You may want to move the <code class="docutils literal notranslate"><span class="pre">GtkBox</span></code> that is the child of the stack page into
its own composite widget:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;template</span> <span class="na">class=</span><span class="s">&quot;ButtonsPage&quot;</span> <span class="na">parent=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;orientation&quot;</span><span class="nt">&gt;</span>vertical<span class="nt">&lt;/property&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkButton&quot;</span><span class="nt">&gt;</span>
<span class="cm">&lt;!-- ... --&gt;</span>
</pre></div>
</div>
<p>And then reference it from the main UI definition:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStack&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStackPage&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;child&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;ButtonsPage&quot;</span><span class="nt">&gt;</span>
<span class="cm">&lt;!-- ... --&gt;</span>
</pre></div>
</div>
<p>After that, you may want to move the box with the stack into its own composite
widget:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;template</span> <span class="na">class=</span><span class="s">&quot;StackBox&quot;</span> <span class="na">parent=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStack&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkStackPage&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&quot;child&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;ButtonsPage&quot;</span><span class="nt">&gt;</span>
<span class="cm">&lt;!-- ... --&gt;</span>
</pre></div>
</div>
<p>And reference it from the main UI definition:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;GtkBox&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;child&gt;</span>
<span class="nt">&lt;object</span> <span class="na">class=</span><span class="s">&quot;StackBox&quot;</span><span class="nt">&gt;</span>
</pre></div>
</div>
<p>This way we have replace one big UI definition file with three smaller ones.</p>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="prev-page" href="drag-and-drop.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Drag and Drop</div>
</div>
</a>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
Contents
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Widget Templates</a><ul>
<li><a class="reference internal" href="#using-a-template">Using a template</a></li>
<li><a class="reference internal" href="#when-to-use-templates">When to use templates</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</main>
</div><script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/scripts/furo.js"></script>
<script src="../_static/tabs.js"></script>
</body>
</html>