AmtkFactory

AmtkFactory — Factory base class

Functions

Properties

GtkApplication * application Read / Write / Construct Only
AmtkFactoryFlags default-flags Read / Write

Types and Values

Object Hierarchy

    GFlags
    ╰── AmtkFactoryFlags
    GObject
    ╰── AmtkFactory

Includes

#include <amtk/amtk.h>

Description

AmtkFactory is a base class to create menu or toolbar items (or anything else) from AmtkActionInfo's. A factory function accesses an AmtkActionInfo from the AmtkActionInfoCentralStore.

A GtkApplication can be associated so that factory functions can call gtk_application_set_accels_for_action() with the accelerators returned by amtk_action_info_get_accels() (this erases previously set accelerators for that action, if any). Note that gtk_application_set_accels_for_action() is called by factory functions and not by amtk_action_info_store_add(), so that libraries can provide their own store and the accelerators are set to the GtkApplication only if an AmtkActionInfo is actually used.

AmtkFactoryFlags permits to control how a factory function creates the object, to ignore some steps. Factory functions should be declined in two variants: a simple form which takes the value of the “default-flags” property, and the same function with the _full suffix which takes an AmtkFactoryFlags argument and ignores the “default-flags”. See for example amtk_factory_create_menu_item() and amtk_factory_create_menu_item_full().

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 notes about the functions that create GtkMenuItem's:

Code example to create a menu

How to create a GtkMenuBar with AmtkFactory. Each submenu is created by a separate function, to make the code clearer.

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

AmtkFactory has functions to create GtkToolItem's.

Code example to create a toolbar

How to create a GtkToolbar with AmtkFactory.

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
static GtkWidget *
create_toolbar (void)
{
  GtkToolbar *toolbar;
  AmtkFactory *factory;

  toolbar = GTK_TOOLBAR (gtk_toolbar_new ());

  // 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);
}

Functions

amtk_factory_new ()

AmtkFactory *
amtk_factory_new (GtkApplication *application);

Creates a new AmtkFactory object. Associating a GtkApplication is optional.

Parameters

application

a GtkApplication, or NULL.

[nullable]

Returns

a new AmtkFactory.

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).

Returns

a new AmtkFactory with the default GtkApplication.

Since: 3.0


amtk_factory_get_application ()

GtkApplication *
amtk_factory_get_application (AmtkFactory *factory);

Parameters

factory

an AmtkFactory.

 

Returns

the “application”.

[transfer none][nullable]

Since: 3.0


amtk_factory_get_default_flags ()

AmtkFactoryFlags
amtk_factory_get_default_flags (AmtkFactory *factory);

Parameters

factory

an AmtkFactory.

 

Returns

the “default-flags”.

Since: 3.0


amtk_factory_set_default_flags ()

void
amtk_factory_set_default_flags (AmtkFactory *factory,
                                AmtkFactoryFlags default_flags);

Sets the “default-flags” property.

Parameters

factory

an AmtkFactory.

 

default_flags

the new value.

 

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”.

Parameters

factory

an AmtkFactory.

 

action_name

an action name.

 

Returns

a new GtkMenuItem for action_name .

[transfer floating]

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.

Parameters

factory

an AmtkFactory.

 

action_name

an action name.

 

flags

AmtkFactoryFlags.

 

Returns

a new GtkMenuItem for action_name .

[transfer floating]

Since: 3.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”.

Parameters

factory

an AmtkFactory.

 

action_name

an action name.

 

Returns

a new GtkToolButton for action_name .

[transfer floating]

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.

Parameters

factory

an AmtkFactory.

 

action_name

an action name.

 

flags

AmtkFactoryFlags.

 

Returns

a new GtkToolButton for action_name .

[transfer floating]

Since: 3.0

Types and Values

AmtkFactory

typedef struct _AmtkFactory AmtkFactory;

enum AmtkFactoryFlags

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

Members

AMTK_FACTORY_FLAGS_NONE

No flags.

 

AMTK_FACTORY_IGNORE_GACTION

Do not call gtk_actionable_set_action_name().

 

AMTK_FACTORY_IGNORE_ICON

Do not set an icon.

 

AMTK_FACTORY_IGNORE_LABEL

Do not set a label/short description.

 

AMTK_FACTORY_IGNORE_TOOLTIP

Do not set a tooltip/long description.

 

AMTK_FACTORY_IGNORE_ACCELS

Ignore completely the accelerators.

 

AMTK_FACTORY_IGNORE_ACCELS_FOR_DOC

Ignore the accelerators for documentation purposes only. For example do not add/configure a GtkAccelLabel.

 

AMTK_FACTORY_IGNORE_ACCELS_FOR_APP

Do not call gtk_application_set_accels_for_action().

 

Since: 3.0

Property Details

The “application” property

  “application”              GtkApplication *

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

Flags: Read / Write / Construct Only

Since: 3.0


The “default-flags” property

  “default-flags”            AmtkFactoryFlags

The default AmtkFactoryFlags.

Flags: Read / Write

Since: 3.0