Developer Documentation
  • Developer Docs
  • Writing Apps
    • The Basic Setup
    • Hello World
    • Our First App
      • Metadata
      • The Build System
      • Translations
      • Icons
      • Packaging
      • Continuous Integration
    • Boxes and Grids
    • Popovers
    • Panes
    • Code Style
      • GObject-style Construction
    • Creating Logs
  • APIs
    • Actions
    • Notifications
    • Launchers
    • State Saving
    • Custom Resources
    • Color Scheme
    • System Settings
    • Valadoc
  • AppCenter
    • Publishing Requirements
    • Submission Process
    • Monetizing Your App
    • Publishing Updates
    • Markdown Badges
    • Dashboard
Powered by GitBook

Links

  • Homepage
  • Support
  • Developer
  • Blog

Other Docs

  • HIG
  • Contributor Guide

Made with ❤️ by contributors from all over the world

On this page
  • Gtk.HeaderBar
  • GLib.SimpleAction
  • Granite.markup_accel_tooltip

Was this helpful?

Edit on GitHub
Export as PDF
  1. APIs

Actions

Creating tool items, GLib.Actions, and keyboard shortcuts

PreviousCreating LogsNextNotifications

Last updated 1 year ago

Was this helpful?

GTK and GLib have a powerful API called which can be used to define the primary actions of your app, assign them keyboard shortcuts, use them as entry points for your app and tie them to widgets like Buttons and Menu Items. In this section, we're going to create a Quit action for your app with an assigned keyboard shortcut and a Button that shows that shortcut in a tooltip.

Gtk.HeaderBar

Application.vala
protected override void activate () {
    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "Actions",
        titlebar = headerbar
    };
    main_window.present ();
}

Since we're using this HeaderBar as our app's main titlebar, we need to set show_title_buttons to true so that GTK knows to include window controls. We can then override our Window's built-in titlebar with the titlebar property.

Application.vala
protected override void activate () {
    var button = new Gtk.Button.from_icon_name ("process-stop");
    button.add_css_class (Granite.STYLE_CLASS_LARGE_ICONS);

    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };
    headerbar.pack_start (button);
    
    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "Actions",
        titlebar = headerbar
    };
    main_window.present ();
}

Build and run your app. You can see that it now has a custom HeaderBar with a big red icon in it. But when you click on it, nothing happens.

GLib.SimpleAction

Define a new Quit action and register it with Application from inside the startup method:

Application.vala
protected override void startup () {
    base.startup ();

    var quit_action = new SimpleAction ("quit", null);

    add_action (quit_action);
    set_accels_for_action ("app.quit",  {"<Control>q", "<Control>w"});
    quit_action.activate.connect (quit);
}

You'll notice that we do a few things here:

  • Set the "accelerators" (keyboard shortcuts) for "app.quit" to <Control>q and <Control>w. Notice that the action name is prefixed with app; this refers to the namespace of the ActionMap built in to Gtk.Application

Now we can tie the action to the HeaderBar Button by assigning the action_name property of our Button:

    var button = new Gtk.Button.from_icon_name ("process-stop") {
        action_name = "app.quit"
    };

Build and run your app again and see that you can now quit the app either through the defined keyboard shortcuts or by clicking the Button in the HeaderBar.

Granite.markup_accel_tooltip

First, make sure you've included Granite in the build dependencies declared in your meson.build file, then set the tooltip_markup property of your HeaderBar Button:

executable(
    meson.project_name(),
    'src' / 'Application.vala',
    dependencies: [
        dependency('granite-7'),
        dependency('gtk4')
    ],
    install: true
)
var button = new Gtk.Button.from_icon_name ("process-stop") {
    action_name = "app.quit",
    tooltip_markup = Granite.markup_accel_tooltip (
        get_accels_for_action ("app.quit"),
        "Quit"
    )
};

Build and run your app and then hover over the HeaderBar Button to see its description and associated keyboard shortcuts.

Begin by creating a Gtk.Application with a Gtk.ApplicationWindow as you've done in . Once you have that set up, let's create a new . Typically your app will have a HeaderBar, at the top of the window, which will contain tool items that users will interact with to trigger your app's actions.

Now, create a new with a big colorful icon and add it to the HeaderBar:

elementary OS ships with a large set of system icons that you can use in your app for actions, status, and more. You can browse the full set of named icons using the app, available in AppCenter.

Instantiate a new with the name "quit"

Add the action to our Gtk.Application's

Connect the activate signal of our SimpleAction to Application's function.

Accelerator strings follow a format defined by . You can find a list of key values

Actions defined like this, and registered with Application, can be used as entry points into the app. You can find out more about this integration in .

You may have noticed that in elementary apps you can hover your pointer over tool items to see a description of the button and any available keyboard shortcuts associated with it. We can add the same thing to our Button with .

If you're having trouble, you can view the full example code . You can also learn more from GLib.Action .

previous examples
Gtk.HeaderBar
Gtk.Button
Icon Browser
GLib.SimpleAction
ActionMap
quit ()
Gtk.accelerator_parse
on Valadoc
Granite.markup_accel_tooltip ()
here on GitHub
reference documentation
GLib.Action
Actionable
A Gtk.Application with a HeaderBar containing a large image button
the launchers section