AmtkFactory: Amtk 5 Reference Manual

## AmtkFactory AmtkFactory — Factory functions |

## Functions

AmtkFactory * | amtk_factory_new ()
AmtkFactory * | amtk_factory_new_with_default_application ()
GtkApplication * | amtk_factory_get_application ()
AmtkFactoryFlags | amtk_factory_get_default_flags ()
void | amtk_factory_set_default_flags ()
GtkWidget * | amtk_factory_create_menu_item ()
GtkWidget * | amtk_factory_create_menu_item_full ()
GtkWidget * | amtk_factory_create_check_menu_item ()
GtkWidget * | amtk_factory_create_check_menu_item_full ()
GtkWidget * | amtk_factory_create_simple_menu ()
GtkWidget * | amtk_factory_create_simple_menu_full ()
GMenuItem * | amtk_factory_create_gmenu_item ()
GMenuItem * | amtk_factory_create_gmenu_item_full ()
GtkToolItem * | amtk_factory_create_tool_button ()
GtkToolItem * | amtk_factory_create_tool_button_full ()
GtkMenuToolButton * | amtk_factory_create_menu_tool_button ()
GtkMenuToolButton * | amtk_factory_create_menu_tool_button_full ()
GtkWidget * | amtk_factory_create_shortcut ()
GtkWidget * | amtk_factory_create_shortcut_full ()

## Properties

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

## Types and Values

| AmtkFactory
enum | AmtkFactoryFlags

## Object Hierarchy

        GFlags
        ╰── AmtkFactoryFlags
        GObject
        ╰── AmtkFactory

## Includes

    #include <amtk/amtk.h>

## Description

AmtkFactory contains functions to create various objects such as a menu item, a toolbar item or a GtkShortcutsShortcut, from the information provided by an AmtkActionInfo. 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()`. 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. For an application store, `amtk_action_info_store_set_all_accels_to_app()` is an alternative.

AmtkFactoryFlags permits to control how a factory function creates the object, to ignore some steps. Factory functions are 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 general notes about the functions that create GtkMenuItem's:

- If not ignored by an AmtkFactoryFlags, the first accelerator returned by `amtk_action_info_get_accels()` is set to the GtkAccelLabel of the GtkMenuItem.

- If not ignored by an AmtkFactoryFlags, the tooltip is set with `amtk_menu_item_set_long_description()`, which permits to display it in a GtkStatusbar with `amtk_application_window_connect_menu_to_statusbar()`.

#### 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

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

- The accelerators returned by `amtk_action_info_get_accels()` are not used for documentation purposes in a toolbar, so the `AMTK_FACTORY_IGNORE_ACCELS_FOR_DOC` flag has no impact. The accelerators are documented only in menu items.

#### Code example to create a toolbar

How to create a basic 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
    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.

## Functions

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

#### 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_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.

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |

#### Returns

a new GtkCheckMenuItem for `action_name` .

[transfer floating]

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.

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |
flags | AmtkFactoryFlags. |

#### Returns

a new GtkCheckMenuItem for `action_name` .

[transfer floating]

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

#### Parameters

factory | an AmtkFactory. |
entries | a pointer to the first item in an array of AmtkActionInfoEntry structs. | [array length=n_entries][element-type AmtkActionInfoEntry]
n_entries | the length of `entries` , or -1 if `entries` is `NULL`-terminated. |

#### Returns

a new simple GtkMenu for `entries` .

[transfer floating]

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:

- Creates a GtkMenu;

- For each AmtkActionInfoEntry action name from `entries` , creates a GtkMenuItem with `amtk_factory_create_menu_item_full()` with the same `flags` as passed in to this function, and appends it to the GtkMenu, in the same order as provided by the `entries` array.

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

#### Parameters

factory | an AmtkFactory. |
entries | a pointer to the first item in an array of AmtkActionInfoEntry structs. | [array length=n_entries][element-type AmtkActionInfoEntry]
n_entries | the length of `entries` , or -1 if `entries` is `NULL`-terminated. |
flags | AmtkFactoryFlags. |

#### Returns

a new simple GtkMenu for `entries` .

[transfer floating]

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

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |

#### Returns

a new GMenuItem for `action_name` .

[transfer full]

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

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |
flags | AmtkFactoryFlags. |

#### Returns

a new GMenuItem for `action_name` .

[transfer full]

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

#### 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

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

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |

#### Returns

a new GtkMenuToolButton for `action_name` .

[transfer floating]

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.

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |
flags | AmtkFactoryFlags. |

#### Returns

a new GtkMenuToolButton for `action_name` .

[transfer floating]

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

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |

#### Returns

a new GtkShortcutsShortcut for `action_name` .

[transfer floating]

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.

#### Parameters

factory | an AmtkFactory. |
action_name | an action name. |
flags | AmtkFactoryFlags. |

#### Returns

a new GtkShortcutsShortcut for `action_name` .

[transfer floating]

Since: 5.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 associate the created object with the GAction. For example if the object to create is a GtkActionable, 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.

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