Functions¶

	`action_map_add_action_entries_check_dups` (action_map, entries, user_data)
	`finalize` ()
	`gmenu_append_item` (menu, item)
	`gmenu_append_section` (menu, label, section)
	`init` ()
	`menu_item_get_long_description` (menu_item)
	`menu_item_set_icon_name` (item, icon_name)
	`menu_item_set_long_description` (menu_item, long_description)
	`shortcuts_group_new` (title)
	`shortcuts_section_new` (title)
	`shortcuts_window_new` (parent)
	`utils_bind_g_action_to_gtk_action` (g_action_map, detailed_g_action_name_without_prefix, gtk_action_group, gtk_action_name)
	`utils_create_gtk_action` (g_action_map, detailed_g_action_name_with_prefix, gtk_action_group, gtk_action_name)
	`utils_get_shrinkable_menubar` (menubar)
	`utils_recent_chooser_menu_get_item_uri` (menu, item)
	`utils_remove_mnemonic` (str)

Details¶

Amtk.action_map_add_action_entries_check_dups(action_map, entries, user_data)¶

Parameters:

action_map (Gio.ActionMap) – a Gio.ActionMap.
entries ([Gio.ActionEntry]) – a pointer to the first item in an array of Gio.ActionEntry structs.
user_data (object or None) – the user data for signal connections.

A wrapper function for Gio.ActionMap.add_action_entries() that checks duplicates.

This function first checks - for each entry - that the action_map doesn’t already contain a Gio.Action with the same name. A warning is printed if an old action will be dropped. In any case, it then calls Gio.ActionMap.add_action_entries() with the same arguments as passed to this function.

This function also checks if there are duplicates in the entries array itself.

New in version 2.0.

Amtk.finalize()¶

Free the resources allocated by Amtk. For example it unrefs the singleton objects.

It is not mandatory to call this function, it’s just to be friendlier to memory debugging tools. This function is meant to be called at the end of main(). It can be called several times.

New in version 3.0.

Amtk.gmenu_append_item(menu, item)¶

Parameters:

menu (Gio.Menu) – a Gio.Menu.
item (Gio.MenuItem) – a Gio.MenuItem to append.

Like Gio.Menu.append_item() but with (transfer full) for the item parameter.

New in version 5.0.

Amtk.gmenu_append_section(menu, label, section)¶

Parameters:

menu (Gio.Menu) – a Gio.Menu.
label (str or None) – the section label, or None.
section (Gio.Menu) – a Gio.Menu with the items of the section.

Like Gio.Menu.append_section() but with (transfer full) and a different type for the section parameter, and calls Gio.Menu.freeze() on section.

New in version 5.0.

Amtk.init()¶

Initializes the Amtk library (e.g. for the internationalization).

This function can be called several times, but is meant to be called at the beginning of main(), before any other Amtk function call.

New in version 3.0.

Amtk.menu_item_get_long_description(menu_item)¶

Parameters:: menu_item (Gtk.MenuItem) – a Gtk.MenuItem.
Returns:: the long description of menu_item, previously set with Amtk.menu_item_set_long_description().
Return type:: str or None

New in version 2.0.

Amtk.menu_item_set_icon_name(item, icon_name)¶

Parameters:

item (Gtk.MenuItem) – a Gtk.MenuItem.
icon_name (str) – an icon name.

Sets an icon to a Gtk.MenuItem.

If the child widget of item is already a Gtk.Box, all Gtk.Image widgets inside that box are first destroyed. A Gtk.Image for icon_name is then inserted to the box.

If the child widget of item is not a Gtk.Box (it’s usually the Gtk.AccelLabel), it is replaced by a new Gtk.Box and the initial child widget is inserted to the Gtk.Box, alongside the icon.

As a consequence, if you want to call functions on the Gtk.AccelLabel, it’s easier to do it before calling this function.

New in version 2.0.

Deprecated since version 5.9: Use Gtk.ImageMenuItem instead, even if deprecated. This function doesn’t place the icon at the right place.

Amtk.menu_item_set_long_description(menu_item, long_description)¶

Parameters:

menu_item (Gtk.MenuItem) – a Gtk.MenuItem.
long_description (str or None) – the long description, or None to unset it.

Sets the long description of menu_item. A possible use-case is to display it in a Gtk.Statusbar, or as a tooltip.

New in version 2.0.

Amtk.shortcuts_group_new(title)¶

Parameters:: title (str) – the Gtk.ShortcutsGroup :title.
Returns:: a new Gtk.ShortcutsGroup.
Return type:: Gtk.Container

New in version 5.0.

Amtk.shortcuts_section_new(title)¶

Parameters:: title (str) – the Gtk.ShortcutsSection :title.
Returns:: a new Gtk.ShortcutsSection.
Return type:: Gtk.Container

New in version 5.0.

Amtk.shortcuts_window_new(parent)¶

Parameters:: parent (Gtk.Window) – the Gtk.Window :transient-for.
Returns:: a new Gtk.ShortcutsWindow.
Return type:: Gtk.ShortcutsWindow

Creates a new Gtk.ShortcutsWindow. The Gtk.Window :modal property is set to True.

It is on purpose that the return type is Gtk.ShortcutsWindow, not Gtk.Widget or something else, so in C when you declare the variable as Gtk.ShortcutsWindow it’s easier to find it later (searching “GtkShortcuts” will return something in your codebase).

New in version 5.0.

Amtk.utils_bind_g_action_to_gtk_action(g_action_map, detailed_g_action_name_without_prefix, gtk_action_group, gtk_action_name)¶

Parameters:

g_action_map (Gio.ActionMap) – a Gio.ActionMap.
detailed_g_action_name_without_prefix (str) – a detailed Gio.Action name without the Gio.ActionMap prefix; the Gio.Action must be present in g_action_map.
gtk_action_group (Gtk.ActionGroup) – a Gtk.ActionGroup.
gtk_action_name (str) – a Gtk.Action name present in gtk_action_group.

Utility function to be able to port an application gradually to Gio.Action, when Gtk.UIManager and Gtk.Action are still used. Porting to Gio.Action should be the first step.

For detailed_g_action_name_without_prefix, see the Gio.Action.parse_detailed_name() function. The "app." or "win." prefix (or any other Gio.ActionMap prefix) must not be included in detailed_g_action_name_without_prefix. For example a valid detailed_g_action_name_without_prefix is "open" or "insert-command::foobar".

The same Gio.Action can be bound to several Gtk.Action's (with different parameter values for the Gio.Action), but the reverse is not true, one Gtk.Action cannot be bound to several Gio.Action's.

This function:

Calls Gio.Action.activate() when the Gtk.Action Gtk.Action ::activate signal is emitted.
Binds the Gio.Action Gio.Action :enabled property to the Gtk.Action Gtk.Action :sensitive property. The binding is done with the GObject.BindingFlags.BIDIRECTIONAL and GObject.BindingFlags.SYNC_CREATE flags, the source is the Gio.Action and the target is the Gtk.Action.

When using this function, you should set the callback to None in the corresponding Gtk.ActionEntry.

New in version 4.0.

Amtk.utils_create_gtk_action(g_action_map, detailed_g_action_name_with_prefix, gtk_action_group, gtk_action_name)¶

Parameters:

g_action_map (Gio.ActionMap) – a Gio.ActionMap.
detailed_g_action_name_with_prefix (str) – a detailed Gio.Action name with the Gio.ActionMap prefix; the Gio.Action must be present in g_action_map.
gtk_action_group (Gtk.ActionGroup) – a Gtk.ActionGroup.
gtk_action_name (str) – the name of the Gtk.Action to create and add to gtk_action_group.

Utility function to be able to port an application gradually to Gio.Action and Amtk.ActionInfo, when Gtk.UIManager is still used. This function goes one step further compared to Amtk.utils_bind_g_action_to_gtk_action(). With Amtk.utils_bind_g_action_to_gtk_action(), only the Gio.Action must exist. With Amtk.utils_create_gtk_action(), both the Gio.Action and Amtk.ActionInfo must exist (so typically you need to convert the Gtk.ActionEntry's into Amtk.ActionInfoEntry's).

This function creates a Gtk.Action from a Gio.Action plus its corresponding Amtk.ActionInfo.

The Gtk.Action is created with the information provided by the Amtk.ActionInfo (retrieved with Amtk.ActionInfoCentralStore.lookup() with detailed_g_action_name_with_prefix as argument). Only the first accelerator is taken into account.

Once the Gtk.Action is created, it is added to the gtk_action_group, and Amtk.utils_bind_g_action_to_gtk_action() is called.

New in version 4.0.

Amtk.utils_get_shrinkable_menubar(menubar)¶

Parameters:: menubar (Gtk.MenuBar) – a Gtk.MenuBar.
Returns:: a new widget that contains menubar.
Return type:: Gtk.Widget

This function wraps menubar into a container, to allow the menubar to shrink below its minimum width.

A possible use-case: have two applications side-by-side on a single screen.

New in version 5.6.

Amtk.utils_recent_chooser_menu_get_item_uri(menu, item)¶

Parameters:

menu (Gtk.RecentChooserMenu) – a Gtk.RecentChooserMenu.
item (Gtk.MenuItem) – a Gtk.MenuItem.

Returns:

the URI of item. Free with GLib.free() when no longer needed.

Return type:

str

Gets the URI of item. item must be a child of menu. menu must be a Gtk.RecentChooserMenu.

This function has been written because the value returned by Gtk.RecentChooser.get_current_uri() is not updated when Gtk.MenuItem's of a Gtk.RecentChooserMenu are selected/deselected.

New in version 2.0.

Amtk.utils_remove_mnemonic(str)¶

Parameters:: str (str) – a string.
Returns:: the new string with the mnemonics removed. Free with GLib.free() when no longer needed.
Return type:: str

Removes the mnemonics from str. Single underscores are removed, and two consecutive underscores are replaced by one underscore (see the documentation of Gtk.Label.new_with_mnemonic()).

New in version 5.0.