Static objects

An important detail is that once a factory function has created an object, the object is not updated if the corresponding AmtkActionInfo is modified afterwards. AmtkActionInfo doesn't have a notify signal, and it is anyway discouraged to modify an AmtkActionInfo after being added to an AmtkActionInfoStore. An AmtkActionInfoStore is meant to be something static, created on application startup. Updating automatically menu and toolbar items is out of scope for the Amtk library. If for example action accelerators can be modified at run-time, the menu needs to be re-generated.

Menus

Some general notes about the functions that create GtkMenuItem's:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

static GtkWidget *
create_file_submenu (void)
{
  GtkMenuShell *file_submenu;
  AmtkFactory *factory;

  file_submenu = GTK_MENU_SHELL (gtk_menu_new ());

  factory = amtk_factory_new_with_default_application ();
  gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "win.open"));
  gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "win.save"));
  gtk_menu_shell_append (file_submenu, gtk_separator_menu_item_new ());
  gtk_menu_shell_append (file_submenu, amtk_factory_create_menu_item (factory, "app.quit"));
  g_object_unref (factory);

  return GTK_WIDGET (file_submenu);
}

static GtkWidget *
create_help_submenu (void)
{
  GtkMenuShell *help_submenu;
  AmtkFactory *factory;

  help_submenu = GTK_MENU_SHELL (gtk_menu_new ());

  factory = amtk_factory_new_with_default_application ();
  gtk_menu_shell_append (help_submenu, amtk_factory_create_menu_item (factory, "app.about"));
  g_object_unref (factory);

  return GTK_WIDGET (help_submenu);
}

static GtkWidget *
create_menu_bar (void)
{
  GtkWidget *file_menu_item;
  GtkWidget *help_menu_item;
  GtkWidget *menu_bar;

  file_menu_item = gtk_menu_item_new_with_mnemonic ("_File");
  gtk_menu_item_set_submenu (GTK_MENU_ITEM (file_menu_item),
                             create_file_submenu ());

  help_menu_item = gtk_menu_item_new_with_mnemonic ("_Help");
  gtk_menu_item_set_submenu (GTK_MENU_ITEM (help_menu_item),
                             create_help_submenu ());

  menu_bar = gtk_menu_bar_new ();
  gtk_menu_shell_append (GTK_MENU_SHELL (menu_bar), file_menu_item);
  gtk_menu_shell_append (GTK_MENU_SHELL (menu_bar), help_menu_item);

  // Additionally, it is a good place to call
  // amtk_action_info_store_check_all_used() here.

  return menu_bar;
}

Toolbars

Some general notes about the functions that create GtkToolItem's:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

static GtkWidget *
create_toolbar (void)
{
  GtkToolbar *toolbar;
  AmtkFactory *factory;

  toolbar = GTK_TOOLBAR (gtk_toolbar_new ());

  // Small performance improvement:
  // Do not associate a GtkApplication, because the menu has already been
  // generated, the menu contains all actions, so
  // gtk_application_set_accels_for_action() has already been called for all
  // actions. Another way is to set the AMTK_FACTORY_IGNORE_ACCELS_FOR_APP
  // flag.
  factory = amtk_factory_new (NULL);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.new-file"), -1);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.open"), -1);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.save"), -1);
  gtk_toolbar_insert (toolbar, gtk_separator_tool_item_new (), -1);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.cut"), -1);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.copy"), -1);
  gtk_toolbar_insert (toolbar, amtk_factory_create_tool_button (factory, "win.paste"), -1);
  g_object_unref (factory);

  return GTK_WIDGET (toolbar);
}

Modern UI with a GtkHeaderBar

To have an example code, see tests/test-headerbar.c in the git repository of Amtk.

amtk_factory_new ()

AmtkFactory *
amtk_factory_new (GtkApplication *application);

Creates a new AmtkFactory object. Associating a GtkApplication is optional, if it is NULL gtk_application_set_accels_for_action() won't be called.

Since: 3.0

amtk_factory_new_with_default_application ()

AmtkFactory *
amtk_factory_new_with_default_application
                               (void);

Calls amtk_factory_new() with g_application_get_default() (it must be a GtkApplication).

Since: 3.0

amtk_factory_get_application ()

GtkApplication *
amtk_factory_get_application (AmtkFactory *factory);

Since: 3.0

amtk_factory_get_default_flags ()

AmtkFactoryFlags
amtk_factory_get_default_flags (AmtkFactory *factory);

Since: 3.0

amtk_factory_set_default_flags ()

void
amtk_factory_set_default_flags (AmtkFactory *factory,
                                AmtkFactoryFlags default_flags);

Sets the “default-flags” property.

Since: 3.0

amtk_factory_create_menu_item ()

GtkWidget *
amtk_factory_create_menu_item (AmtkFactory *factory,
                               const gchar *action_name);

Creates a new GtkMenuItem for action_name with the “default-flags”.

Since: 3.0

amtk_factory_create_menu_item_full ()

GtkWidget *
amtk_factory_create_menu_item_full (AmtkFactory *factory,
                                    const gchar *action_name,
                                    AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

Since: 3.0

amtk_factory_create_check_menu_item ()

GtkWidget *
amtk_factory_create_check_menu_item (AmtkFactory *factory,
                                     const gchar *action_name);

Creates a new GtkCheckMenuItem for action_name with the “default-flags”.

See the documentation of amtk_factory_create_check_menu_item_full() for more information.

Since: 3.0

amtk_factory_create_check_menu_item_full ()

GtkWidget *
amtk_factory_create_check_menu_item_full
                               (AmtkFactory *factory,
                                const gchar *action_name,
                                AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

Note that since it is a GtkCheckMenuItem the icon is not set, even if it would be possible with amtk_menu_item_set_icon_name().

If the action controls a boolean property, think about using GPropertyAction.

Since: 3.0

amtk_factory_create_simple_menu ()

GtkWidget *
amtk_factory_create_simple_menu (AmtkFactory *factory,
                                 const AmtkActionInfoEntry *entries,
                                 gint n_entries);

Calls amtk_factory_create_simple_menu_full() with the “default-flags”.

Since: 5.0

amtk_factory_create_simple_menu_full ()

GtkWidget *
amtk_factory_create_simple_menu_full (AmtkFactory *factory,
                                      const AmtkActionInfoEntry *entries,
                                      gint n_entries,
                                      AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

This function:

So this function is useful only if the GtkMenu contains only simple GtkMenuItem's, not GtkCheckMenuItem's nor GtkRadioMenuItem's.

Since: 5.0

amtk_factory_create_gmenu_item ()

GMenuItem *
amtk_factory_create_gmenu_item (AmtkFactory *factory,
                                const gchar *action_name);

Calls amtk_factory_create_gmenu_item_full() with the “default-flags”.

Since: 5.0

amtk_factory_create_gmenu_item_full ()

GMenuItem *
amtk_factory_create_gmenu_item_full (AmtkFactory *factory,
                                     const gchar *action_name,
                                     AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

Creates a new GMenuItem for action_name . It ignores the tooltip, i.e. the return value of amtk_action_info_get_tooltip().

Since: 5.0

amtk_factory_create_tool_button ()

GtkToolItem *
amtk_factory_create_tool_button (AmtkFactory *factory,
                                 const gchar *action_name);

Creates a new GtkToolButton for action_name with the “default-flags”.

Since: 3.0

amtk_factory_create_tool_button_full ()

GtkToolItem *
amtk_factory_create_tool_button_full (AmtkFactory *factory,
                                      const gchar *action_name,
                                      AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

Since: 3.0

amtk_factory_create_menu_tool_button ()

GtkMenuToolButton *
amtk_factory_create_menu_tool_button (AmtkFactory *factory,
                                      const gchar *action_name);

Creates a new GtkMenuToolButton for action_name with the “default-flags”.

See the documentation of amtk_factory_create_menu_tool_button_full() for more information.

Since: 3.0

amtk_factory_create_menu_tool_button_full ()

GtkMenuToolButton *
amtk_factory_create_menu_tool_button_full
                               (AmtkFactory *factory,
                                const gchar *action_name,
                                AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

After calling this function, you need to use the GtkMenuToolButton API to set the menu and also possibly set a tooltip to the arrow.

Since: 3.0

amtk_factory_create_shortcut ()

GtkWidget *
amtk_factory_create_shortcut (AmtkFactory *factory,
                              const gchar *action_name);

Calls amtk_factory_create_shortcut_full() with the “default-flags”.

Since: 5.0

amtk_factory_create_shortcut_full ()

GtkWidget *
amtk_factory_create_shortcut_full (AmtkFactory *factory,
                                   const gchar *action_name,
                                   AmtkFactoryFlags flags);

This function ignores the “default-flags” property and takes the flags argument instead.

This function creates a new GtkShortcutsShortcut for action_name .

For the “title”, the tooltip has the priorioty, with the label as fallback if the tooltip is NULL (the mnemonic is removed from the label with amtk_utils_remove_mnemonic()). This can be controlled with the AMTK_FACTORY_IGNORE_TOOLTIP and AMTK_FACTORY_IGNORE_LABEL flags.

The “accelerator” property is set with only the *first* accel returned by amtk_action_info_get_accels(). This step can be ignored with AMTK_FACTORY_IGNORE_ACCELS or AMTK_FACTORY_IGNORE_ACCELS_FOR_DOC.

The “action-name” property is set to action_name if the AMTK_FACTORY_IGNORE_GACTION flag isn't set. Note that with “action-name” all accelerators are displayed (if set to the GtkApplication).

So depending on whether you want to show only the first accelerator or all accelerators, you need to set flags appropriately.

Since: 5.0

AmtkFactory

typedef struct _AmtkFactory AmtkFactory;

enum AmtkFactoryFlags

AmtkFactoryFlags permits to control how a factory function creates the object, to ignore some steps.

Since: 3.0

The “application” property

  “application”              GtkApplication *

The associated GtkApplication (it is optional, it can be NULL). AmtkFactory has a weak reference to the GtkApplication.

Owner: AmtkFactory

Flags: Read / Write / Construct Only

Since: 3.0

The “default-flags” property

  “default-flags”            AmtkFactoryFlags

The default AmtkFactoryFlags.

Owner: AmtkFactory

Flags: Read / Write

Since: 3.0