Top | ![]() |
![]() |
![]() |
![]() |
GtkApplication * | application | Read / Write / Construct Only |
AmtkFactoryFlags | default-flags | Read / Write |
AmtkFactory contains functions to create menu or toolbar items 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 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()
.
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.
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()
.
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; } |
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.
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); } |
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
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
GtkApplication *
amtk_factory_get_application (AmtkFactory *factory
);
Since: 3.0
AmtkFactoryFlags
amtk_factory_get_default_flags (AmtkFactory *factory
);
Since: 3.0
void amtk_factory_set_default_flags (AmtkFactory *factory
,AmtkFactoryFlags default_flags
);
Sets the “default-flags” property.
Since: 3.0
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
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
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
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
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
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
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
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
AmtkFactoryFlags permits to control how a factory function creates the object, to ignore some steps.
No flags. |
||
Do not call |
||
Do not set an icon. |
||
Do not set a label/short description. |
||
Do not set a tooltip/long description. |
||
Ignore completely the accelerators. |
||
Ignore the accelerators for documentation purposes only. For example do not add/configure a GtkAccelLabel. |
||
Do not call
|
Since: 3.0
“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
“default-flags”
property“default-flags” AmtkFactoryFlags
The default AmtkFactoryFlags.
Flags: Read / Write
Since: 3.0