File: sec-custom-css-names.html

package info (click to toggle)
gtkmm-documentation 4.12.0-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 25,772 kB
sloc: cpp: 15,541; javascript: 1,208; makefile: 1,080; python: 401; xml: 106; perl: 67; sh: 8
file content (415 lines) | stat: -rw-r--r-- 15,303 bytes
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="highlight.min.css">
<script src="highlight.min.js"></script><script>
      hljs.configure({languages: ['cpp']});
      hljs.highlightAll();
    </script><title>Custom CSS Names</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Programming with gtkmm 4">
<link rel="up" href="chapter-customwidgets.html" title="Chapter 28. Custom Widgets">
<link rel="prev" href="sec-custom-widgets.html" title="Custom Widgets">
<link rel="next" href="chapter-multi-threaded-programs.html" title="Chapter 29. Multi-threaded programs">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Custom CSS Names</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-custom-widgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Chapter 28. Custom Widgets</th>
<td width="20%" align="right"> <a accesskey="n" href="chapter-multi-threaded-programs.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-custom-css-names"></a>Custom CSS Names</h2></div></div></div>


<p>Many aspects of the look of widgets are controlled by CSS (Cascading Style
Sheet) files. With CSS files you can choose color, font, line thickness, etc.
If you give some widgets their own names or their own CSS classes, you can define
CSS rules that apply only to those widgets, for instance certain buttons,
without affecting other similar widgets.</p>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="css-widget-class-name"></a>CSS Node Name, Widget Name, CSS Class Name</h3></div></div></div>


<p>There are three ways of referring from a widget to data in a CSS file:
  </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="methodname">gtk_widget_class_set_css_name()</code>
    can only be called from the class init function. It sets the CSS node name
    of all instances of a class (a GType). See the <a class="link" href="sec-custom-widgets.html#custom-init-functions" title="Class Init and Instance Init Functions">
    Class Init and Instance Init Functions</a> section.</p></li>
<li class="listitem"><p><code class="methodname">Gtk::Widget::set_name()</code>
    can be called from a C++ constructor. It sets the name of
    a widget instance.</p></li>
<li class="listitem"><p><code class="methodname">Gtk::Widget::add_class_name()</code>
    can be called from a C++ constructor. It adds the name of a CSS class,
    used by a widget instance.</p></li>
</ul></div>
<p>
The following example shows a button with its own CSS node name, a label with
a widget name and a label that uses its own CSS class.</p>
</div>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="custom-style-information"></a>Custom Style Information</h3></div></div></div>


<p>To add a style sheet to an application, use one of the
<code class="methodname">Gtk::CssProvider::load_from_*()</code> methods.
Then add it with <code class="methodname">Gtk::StyleProvider::add_provider_for_display()</code>
(available since <span class="application">gtkmm</span> 4.10) or <code class="methodname">Gtk::StyleContext::add_provider_for_display()</code>.
<code class="classname">Gtk::StyleContext</code> also contains methods to read some style
information, but this class is deprecated since <span class="application">gtkmm</span> 4.10.</p>

<p>CSS files are described in the documentation of GTK.</p>
</div>

<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="custom-css-name-example"></a>Example</h3></div></div></div>


<p>This example implements a button and two labels with custom style information.</p>

<div class="figure">
<a name="figure-custom-css-name"></a><p class="title"><b>Figure 28.3. Custom CSS Name</b></p>
<div class="figure-contents">
  
  <div class="screenshot">
    <div class="mediaobject"><img src="figures/custom_css_name.png" alt="Custom CSS Name"></div>
  </div>
</div>
</div>
<br class="figure-break">

<p><a class="ulink" href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/custom/custom_css_name/" target="_top">Source Code</a></p>

<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;
#include "mybutton.h"

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  ~ExampleWindow() override;

protected:
  // Signal handlers:
  void on_button_quit();
  static void on_parsing_error(const Glib::RefPtr&lt;const Gtk::CssSection&gt;&amp; section,
    const Glib::Error&amp; error);

  // Child widgets:
  Gtk::Box m_VBox;
  MyButton m_Button_Child;
  Gtk::Label m_Label_Child1;
  Gtk::Label m_Label_Child2;
  Gtk::Box m_ButtonBox;
  Gtk::Button m_Button_Quit;

  Glib::RefPtr&lt;Gtk::CssProvider&gt; m_refCssProvider;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</code></pre>
<p>File: <code class="filename">mybutton.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLE_MYBUTTON_H
#define GTKMM_EXAMPLE_MYBUTTON_H

#include &lt;gtkmm/button.h&gt;
#include "myextrainit.h"

class MyButton : public MyExtraInit, public Gtk::Button
{
public:
  MyButton(const Glib::ustring&amp; label, bool mnemonic=false);
  ~MyButton() override;
};

#endif //GTKMM_EXAMPLE_MYBUTTON_H
</code></pre>
<p>File: <code class="filename">myextrainit.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#ifndef GTKMM_EXAMPLE_MYEXTRAINIT_H
#define GTKMM_EXAMPLE_MYEXTRAINIT_H

#include &lt;glibmm/extraclassinit.h&gt;
#include &lt;glibmm/ustring.h&gt;

// Calls gtk_widget_class_set_css_name() in the class init function.
class MyExtraInit : public Glib::ExtraClassInit
{
public:
  MyExtraInit(const Glib::ustring&amp; css_name);

private:
  Glib::ustring m_css_name;
};

#endif //GTKMM_EXAMPLE_MYEXTRAINIT_H
</code></pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;iostream&gt;
#include &lt;gtkmm/version.h&gt;

#define HAS_STYLE_PROVIDER_ADD_PROVIDER_FOR_DISPLAY GTKMM_CHECK_VERSION(4,9,1)

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::Orientation::VERTICAL),
  m_Button_Child("Button with custom CSS node name"),
  m_Label_Child1("Label with custom name"),
  m_Label_Child2("Label with custom CSS class"),
  m_Button_Quit("Quit")
{
  set_title("Custom CSS name example");
  set_default_size(400, 200);

  m_VBox.set_margin(10);
  m_VBox.set_spacing(5);
  set_child(m_VBox);

  // There are 3 ways to set custom CSS data for a widget:
  // 1. The CSS name can be set for a GType with gtk_widget_class_set_css_name().
  // 2. The CSS name can be set for a widget instance with gtk_widget_set_name()
  //    (Gtk::Widget::set_name()).
  // 3. A CSS class can be set for a widget instance with
  //    gtk_widget_add_css_class() (Gtk::Widget::add_css_class()).
  //
  // gtk_widget_class_set_css_name(), if used, must be called in the class init
  // function. It has not been wrapped in a C++ function.
  // Gtk::Widget::set_name() and Gtk::Widget::add_css_class() can be called in
  // a C++ constructor.

  // CSS widget name, which must be used in the CSS file, preceded by "#".
  m_Label_Child1.set_name("my-label1");

  // CSS class name, which must be used in the CSS file, preceded by ".".
  m_Label_Child2.add_css_class("my-label2");

  // Add the child widgets to m_VBox:
  m_VBox.append(*Gtk::make_managed&lt;Gtk::Label&gt;("Ordinary label"));
  m_VBox.append(m_Button_Child);
  m_VBox.append(m_Label_Child1);
  m_VBox.append(m_Label_Child2);
  m_VBox.set_expand();
  m_VBox.append(m_ButtonBox);

  m_ButtonBox.append(m_Button_Quit);
  m_ButtonBox.set_margin(6);
  m_Button_Quit.set_hexpand(true);
  m_Button_Quit.set_halign(Gtk::Align::END);
  m_Button_Quit.signal_clicked().connect( sigc::mem_fun(*this,
              &amp;ExampleWindow::on_button_quit) );

  // Load extra CSS file.
  m_refCssProvider = Gtk::CssProvider::create();
#if HAS_STYLE_PROVIDER_ADD_PROVIDER_FOR_DISPLAY
  Gtk::StyleProvider::add_provider_for_display(get_display(), m_refCssProvider,
    GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
#else
  Gtk::StyleContext::add_provider_for_display(get_display(), m_refCssProvider,
    GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
#endif

  m_refCssProvider-&gt;signal_parsing_error().connect(
    [](const auto&amp; section, const auto&amp; error)
    { on_parsing_error(section, error); }
  );
  m_refCssProvider-&gt;load_from_path("custom_gtkmm.css");
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_quit()
{
  set_visible(false);
}

void ExampleWindow::on_parsing_error(const Glib::RefPtr&lt;const Gtk::CssSection&gt;&amp; section,
  const Glib::Error&amp; error)
{
  std::cerr &lt;&lt; "on_parsing_error(): " &lt;&lt; error.what() &lt;&lt; std::endl;
  if (section)
  {
    const auto file = section-&gt;get_file();
    if (file)
    {
      std::cerr &lt;&lt; "  URI = " &lt;&lt; file-&gt;get_uri() &lt;&lt; std::endl;
    }

    auto start_location = section-&gt;get_start_location();
    auto end_location = section-&gt;get_end_location();
    std::cerr &lt;&lt; "  start_line = " &lt;&lt; start_location.get_lines()+1
              &lt;&lt; ", end_line = " &lt;&lt; end_location.get_lines()+1 &lt;&lt; std::endl;
    std::cerr &lt;&lt; "  start_position = " &lt;&lt; start_location.get_line_chars()
              &lt;&lt; ", end_position = " &lt;&lt; end_location.get_line_chars() &lt;&lt; std::endl;
  }
}
</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "examplewindow.h"
#include &lt;gtkmm/application.h&gt;

int main(int argc, char* argv[])
{
  auto app = Gtk::Application::create("org.gtkmm.example");

  // Shows the window and returns when it is closed.
  return app-&gt;make_window_and_run&lt;ExampleWindow&gt;(argc, argv);
}
</code></pre>
<p>File: <code class="filename">mybutton.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "mybutton.h"
#include &lt;gtk/gtk.h&gt; // For GTK_IS_BUTTON()
#include &lt;iostream&gt;

MyButton::MyButton(const Glib::ustring&amp; label, bool mnemonic)
  :
  // The GType name will actually be gtkmm__CustomObject_MyButton
  Glib::ObjectBase("MyButton"),
  MyExtraInit("my-button"), // CSS node name, which must be used in the CSS file.
  Gtk::Button(label, mnemonic)
{
  // This shows the GType name:
  std::cout &lt;&lt; "GType name: " &lt;&lt; G_OBJECT_TYPE_NAME(gobj()) &lt;&lt; std::endl;

  // This shows that the GType still derives from GtkButton:
  std::cout &lt;&lt; "Gtype is a GtkButton?: " &lt;&lt; GTK_IS_BUTTON(gobj()) &lt;&lt; std::endl;

  // The CSS name can be set either
  // - for a GType (in this case for your custom class) with gtk_widget_class_set_css_name(), or
  // - for a widget instance with gtk_widget_set_name() (Gtk::Widget::set_name()).
  //
  // gtk_widget_class_set_css_name(), if used, must be called in the class init function.
  // It has not been wrapped in a C++ function.
  // Gtk::Widget::set_name() can be called in a C++ constructor.
  //
  // Another alternative: The custom button inherits the CSS name "button" from
  // GtkButton. That name can be used in the CSS file.
}

MyButton::~MyButton()
{
}
</code></pre>
<p>File: <code class="filename">myextrainit.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "myextrainit.h"
#include &lt;gtkmm/widget.h&gt;
#include &lt;gtk/gtk.h&gt;

namespace
{
using BaseObjectType = GtkWidget;
using BaseClassType = GtkWidgetClass;

// These callback functions are called from GLib (a C library).
// They shall have C linkage. (Many compilers accept callback functions
// with C++ linkage, but such a program has undefined behavior.)
//
// If you want the functions with C linkage to have internal linkage,
// they must be declared 'static', even though they are defined in an anonymous
// namespace. The compiler respects namespace declarations of functions
// with C linkage, but the linker does not.
extern "C"
{
// Extra class init function.
static void class_init_function(void* g_class, void* class_data)
{
  g_return_if_fail(GTK_IS_WIDGET_CLASS(g_class));

  const auto klass = static_cast&lt;BaseClassType*&gt;(g_class);
  const auto css_name = static_cast&lt;Glib::ustring*&gt;(class_data);

  gtk_widget_class_set_css_name(klass, css_name-&gt;c_str());
}

// Extra instance init function.
static void instance_init_function(GTypeInstance* instance, void* /* g_class */)
{
  g_return_if_fail(GTK_IS_WIDGET(instance));

  // Nothing to do here.
  // This extra instance init function just shows how such a function can
  // be added to a custom widget, if necessary.
}
} // extern "C"
} // anonymous namespace

MyExtraInit::MyExtraInit(const Glib::ustring&amp; css_name)
:
Glib::ExtraClassInit(class_init_function, &amp;m_css_name, instance_init_function),
m_css_name(css_name)
{
}
</code></pre>
<p>File: <code class="filename">custom_gtkmm.css</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">/* Example of a CSS style sheet. */

my-button {
  background-color: red;
  color:            blue;
  padding:          10px 15px 20px 5px; /* top right bottom left */
  border:           solid black 2px;
  border-radius:    8px;   
}
my-button:active {
  background-color: rgb(0,255,0);
}
#my-label1 {
  background-color: rgb(180,180,180);
  color:            rgb(0,255,255);
  padding:          10px 15px 10px 25px; /* top right bottom left */
}
#my-label1:hover {
  background-color: rgb(220,220,220);
}
.my-label2 {
  background-color: rgb(180,180,100);
  color:            black;
  padding:          5px 15px 5px 25px; /* top right bottom left */
}
.my-label2:hover {
  background-color: rgb(220,220,140);
}
</code></pre>

</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-custom-widgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-customwidgets.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="chapter-multi-threaded-programs.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Custom Widgets </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Chapter 29. Multi-threaded programs</td>
</tr>
</table>
</div>
</body>
</html>