Commit 35444199e88d49819842c4d14eb124a57d4a5a97 - amtk

meson: gtk-doc Sébastien Wilmet 3 years ago

11 changed file(s) with 473 addition(s) and 420 deletion(s). Raw diff Collapse all Expand all

-182

~~docs/reference/amtk-5.0-sections.txt~~ less more

0		<INCLUDE>amtk/amtk.h</INCLUDE>
1
2		<SECTION>
3		<FILE>amtk-init</FILE>
4		<TITLE>Amtk Initialization and Finalization</TITLE>
5		amtk_init
6		amtk_finalize
7		</SECTION>
8
9		<SECTION>
10		<FILE>amtk-application-window</FILE>
11		AmtkApplicationWindow
12		amtk_application_window_get_from_gtk_application_window
13		amtk_application_window_get_application_window
14		amtk_application_window_get_statusbar
15		amtk_application_window_set_statusbar
16		amtk_application_window_connect_menu_to_statusbar
17		amtk_application_window_connect_recent_chooser_menu_to_statusbar
18		amtk_application_window_create_open_recent_menu
19		amtk_application_window_create_open_recent_menu_item
20		<SUBSECTION Standard>
21		AMTK_APPLICATION_WINDOW
22		AMTK_APPLICATION_WINDOW_CLASS
23		AMTK_APPLICATION_WINDOW_GET_CLASS
24		AMTK_IS_APPLICATION_WINDOW
25		AMTK_IS_APPLICATION_WINDOW_CLASS
26		AMTK_TYPE_APPLICATION_WINDOW
27		AmtkApplicationWindowClass
28		AmtkApplicationWindowPrivate
29		amtk_application_window_get_type
30		</SECTION>
31
32		<SECTION>
33		<FILE>amtk-action-info</FILE>
34		AmtkActionInfo
35		AmtkActionInfoEntry
36		amtk_action_info_new
37		amtk_action_info_new_from_entry
38		amtk_action_info_ref
39		amtk_action_info_unref
40		amtk_action_info_copy
41		amtk_action_info_get_action_name
42		amtk_action_info_set_action_name
43		amtk_action_info_get_icon_name
44		amtk_action_info_set_icon_name
45		amtk_action_info_get_label
46		amtk_action_info_set_label
47		amtk_action_info_get_tooltip
48		amtk_action_info_set_tooltip
49		amtk_action_info_get_accels
50		amtk_action_info_set_accels
51		amtk_action_info_mark_as_used
52		amtk_action_info_has_been_used
53		<SUBSECTION Standard>
54		amtk_action_info_get_type
55		AMTK_TYPE_ACTION_INFO
56		</SECTION>
57
58		<SECTION>
59		<FILE>amtk-action-info-store</FILE>
60		AmtkActionInfoStore
61		amtk_action_info_store_new
62		amtk_action_info_store_add
63		amtk_action_info_store_add_entries
64		amtk_action_info_store_lookup
65		amtk_action_info_store_set_all_accels_to_app
66		amtk_action_info_store_check_all_used
67		<SUBSECTION Standard>
68		AMTK_ACTION_INFO_STORE
69		AMTK_ACTION_INFO_STORE_CLASS
70		AMTK_ACTION_INFO_STORE_GET_CLASS
71		AMTK_IS_ACTION_INFO_STORE
72		AMTK_IS_ACTION_INFO_STORE_CLASS
73		AMTK_TYPE_ACTION_INFO_STORE
74		AmtkActionInfoStoreClass
75		AmtkActionInfoStorePrivate
76		amtk_action_info_store_get_type
77		</SECTION>
78
79		<SECTION>
80		<FILE>amtk-action-info-central-store</FILE>
81		AmtkActionInfoCentralStore
82		amtk_action_info_central_store_get_singleton
83		amtk_action_info_central_store_lookup
84		<SUBSECTION Standard>
85		AMTK_ACTION_INFO_CENTRAL_STORE
86		AMTK_ACTION_INFO_CENTRAL_STORE_CLASS
87		AMTK_ACTION_INFO_CENTRAL_STORE_GET_CLASS
88		AMTK_IS_ACTION_INFO_CENTRAL_STORE
89		AMTK_IS_ACTION_INFO_CENTRAL_STORE_CLASS
90		AMTK_TYPE_ACTION_INFO_CENTRAL_STORE
91		AmtkActionInfoCentralStoreClass
92		AmtkActionInfoCentralStorePrivate
93		amtk_action_info_central_store_get_type
94		</SECTION>
95
96		<SECTION>
97		<FILE>amtk-action-map</FILE>
98		amtk_action_map_add_action_entries_check_dups
99		</SECTION>
100
101		<SECTION>
102		<FILE>amtk-factory</FILE>
103		AmtkFactory
104		AmtkFactoryFlags
105		amtk_factory_new
106		amtk_factory_new_with_default_application
107		amtk_factory_get_application
108		amtk_factory_get_default_flags
109		amtk_factory_set_default_flags
110		amtk_factory_create_menu_item
111		amtk_factory_create_menu_item_full
112		amtk_factory_create_check_menu_item
113		amtk_factory_create_check_menu_item_full
114		amtk_factory_create_simple_menu
115		amtk_factory_create_simple_menu_full
116		amtk_factory_create_gmenu_item
117		amtk_factory_create_gmenu_item_full
118		amtk_factory_create_tool_button
119		amtk_factory_create_tool_button_full
120		amtk_factory_create_menu_tool_button
121		amtk_factory_create_menu_tool_button_full
122		amtk_factory_create_shortcut
123		amtk_factory_create_shortcut_full
124		<SUBSECTION Standard>
125		AMTK_FACTORY
126		AMTK_FACTORY_CLASS
127		AMTK_FACTORY_GET_CLASS
128		AMTK_IS_FACTORY
129		AMTK_IS_FACTORY_CLASS
130		AMTK_TYPE_FACTORY
131		AmtkFactoryClass
132		AmtkFactoryPrivate
133		amtk_factory_get_type
134		AMTK_TYPE_FACTORY_FLAGS
135		amtk_factory_flags_get_type
136		</SECTION>
137
138		<SECTION>
139		<FILE>amtk-gmenu</FILE>
140		amtk_gmenu_append_item
141		amtk_gmenu_append_section
142		</SECTION>
143
144		<SECTION>
145		<FILE>amtk-menu-item</FILE>
146		amtk_menu_item_get_long_description
147		amtk_menu_item_set_long_description
148		amtk_menu_item_set_icon_name
149		</SECTION>
150
151		<SECTION>
152		<FILE>amtk-menu-shell</FILE>
153		AmtkMenuShell
154		amtk_menu_shell_get_from_gtk_menu_shell
155		amtk_menu_shell_get_menu_shell
156		<SUBSECTION Standard>
157		AMTK_IS_MENU_SHELL
158		AMTK_IS_MENU_SHELL_CLASS
159		AMTK_MENU_SHELL
160		AMTK_MENU_SHELL_CLASS
161		AMTK_MENU_SHELL_GET_CLASS
162		AMTK_TYPE_MENU_SHELL
163		AmtkMenuShellClass
164		AmtkMenuShellPrivate
165		amtk_menu_shell_get_type
166		</SECTION>
167
168		<SECTION>
169		<FILE>amtk-shortcuts</FILE>
170		amtk_shortcuts_window_new
171		amtk_shortcuts_section_new
172		amtk_shortcuts_group_new
173		</SECTION>
174
175		<SECTION>
176		<FILE>amtk-utils</FILE>
177		amtk_utils_remove_mnemonic
178		amtk_utils_recent_chooser_menu_get_item_uri
179		amtk_utils_bind_g_action_to_gtk_action
180		amtk_utils_create_gtk_action
181		</SECTION>

+64

-0

docs/reference/amtk-docs.xml less more

	0	<?xml version="1.0"?>
	1	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	2	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
	3	[
	4	<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
	5	<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
	6	%gtkdocentities;
	7	]>
	8	<book id="index">
	9	<bookinfo>
	10	<title>Amtk &package_api_version; Reference Manual</title>
	11	<releaseinfo>for &package_string;</releaseinfo>
	12	</bookinfo>
	13
	14	<xi:include href="amtk-intro.xml"/>
	15
	16	<part id="api-reference">
	17	<title>Amtk API Reference</title>
	18	<xi:include href="xml/amtk-init.xml"/>
	19	<xi:include href="xml/amtk-application-window.xml"/>
	20	<xi:include href="xml/amtk-action-info.xml"/>
	21	<xi:include href="xml/amtk-action-info-store.xml"/>
	22	<xi:include href="xml/amtk-action-info-central-store.xml"/>
	23	<xi:include href="xml/amtk-action-map.xml"/>
	24	<xi:include href="xml/amtk-factory.xml"/>
	25	<xi:include href="xml/amtk-gmenu.xml"/>
	26	<xi:include href="xml/amtk-menu-item.xml"/>
	27	<xi:include href="xml/amtk-menu-shell.xml"/>
	28	<xi:include href="xml/amtk-shortcuts.xml"/>
	29	<xi:include href="xml/amtk-utils.xml"/>
	30	</part>
	31
	32	<part id="annexes">
	33	<title>Annexes</title>
	34
	35	<chapter id="object-tree">
	36	<title>Object Hierarchy</title>
	37	<xi:include href="xml/tree_index.sgml"/>
	38	</chapter>
	39
	40	<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
	41
	42	<index id="api-index-full">
	43	<title>Index of all symbols</title>
	44	<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
	45	</index>
	46	<index id="api-index-2-0" role="2.0">
	47	<title>Index of new symbols in 2.0</title>
	48	<xi:include href="xml/api-index-2.0.xml"><xi:fallback /></xi:include>
	49	</index>
	50	<index id="api-index-3-0" role="3.0">
	51	<title>Index of new symbols in 3.0</title>
	52	<xi:include href="xml/api-index-3.0.xml"><xi:fallback /></xi:include>
	53	</index>
	54	<index id="api-index-4-0" role="4.0">
	55	<title>Index of new symbols in 4.0</title>
	56	<xi:include href="xml/api-index-4.0.xml"><xi:fallback /></xi:include>
	57	</index>
	58	<index id="api-index-5-0" role="5.0">
	59	<title>Index of new symbols in 5.0</title>
	60	<xi:include href="xml/api-index-5.0.xml"><xi:fallback /></xi:include>
	61	</index>
	62	</part>
	63	</book>

-64

~~docs/reference/amtk-docs.xml.in~~ less more

0		<?xml version="1.0"?>
1		<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
2		"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
3		[
4		<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5		<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
6		%gtkdocentities;
7		]>
8		<book id="index">
9		<bookinfo>
10		<title>Amtk @AMTK_API_VERSION@ Reference Manual</title>
11		<releaseinfo>for Amtk &package_version;</releaseinfo>
12		</bookinfo>
13
14		<xi:include href="amtk-intro.xml"/>
15
16		<part id="api-reference">
17		<title>Amtk API Reference</title>
18		<xi:include href="xml/amtk-init.xml"/>
19		<xi:include href="xml/amtk-application-window.xml"/>
20		<xi:include href="xml/amtk-action-info.xml"/>
21		<xi:include href="xml/amtk-action-info-store.xml"/>
22		<xi:include href="xml/amtk-action-info-central-store.xml"/>
23		<xi:include href="xml/amtk-action-map.xml"/>
24		<xi:include href="xml/amtk-factory.xml"/>
25		<xi:include href="xml/amtk-gmenu.xml"/>
26		<xi:include href="xml/amtk-menu-item.xml"/>
27		<xi:include href="xml/amtk-menu-shell.xml"/>
28		<xi:include href="xml/amtk-shortcuts.xml"/>
29		<xi:include href="xml/amtk-utils.xml"/>
30		</part>
31
32		<part id="annexes">
33		<title>Annexes</title>
34
35		<chapter id="object-tree">
36		<title>Object Hierarchy</title>
37		<xi:include href="xml/tree_index.sgml"/>
38		</chapter>
39
40		<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
41
42		<index id="api-index-full">
43		<title>Index of all symbols</title>
44		<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
45		</index>
46		<index id="api-index-2-0" role="2.0">
47		<title>Index of new symbols in 2.0</title>
48		<xi:include href="xml/api-index-2.0.xml"><xi:fallback /></xi:include>
49		</index>
50		<index id="api-index-3-0" role="3.0">
51		<title>Index of new symbols in 3.0</title>
52		<xi:include href="xml/api-index-3.0.xml"><xi:fallback /></xi:include>
53		</index>
54		<index id="api-index-4-0" role="4.0">
55		<title>Index of new symbols in 4.0</title>
56		<xi:include href="xml/api-index-4.0.xml"><xi:fallback /></xi:include>
57		</index>
58		<index id="api-index-5-0" role="5.0">
59		<title>Index of new symbols in 5.0</title>
60		<xi:include href="xml/api-index-5.0.xml"><xi:fallback /></xi:include>
61		</index>
62		</part>
63		</book>

+170

-0

docs/reference/amtk-intro.xml less more

	0	<?xml version="1.0"?>
	1	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	2	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
	3	[
	4	<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
	5	<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
	6	%gtkdocentities;
	7	]>
	8
	9	<refentry id="amtk-intro">
	10	<refmeta>
	11	<refentrytitle>Amtk Introduction</refentrytitle>
	12	</refmeta>
	13
	14	<refnamediv>
	15	<refname>Amtk Introduction</refname>
	16	<refpurpose>
	17	Introduction to the Actions, Menus and Toolbars Kit for GTK applications.
	18	</refpurpose>
	19	</refnamediv>
	20
	21	<para>
	22	Amtk is the acronym for “Actions, Menus and Toolbars Kit”. Amtk has been
	23	initially created as a basic <link linkend="GtkUIManager">GtkUIManager</link>
	24	replacement based on <link linkend="GAction">GAction</link>.
	25	<link linkend="GtkUIManager">GtkUIManager</link> has been deprecated in
	26	GTK 3 (and removed in GTK 4), without a good replacement for
	27	applications that want to keep a traditional UI (with a
	28	<link linkend="GtkMenuBar">GtkMenuBar</link>, a
	29	<link linkend="GtkToolbar">GtkToolbar</link> and a
	30	<link linkend="GtkStatusbar">GtkStatusbar</link>). Amtk is now suitable for
	31	both a traditional UI and for a new UI with a
	32	<link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “hamburger menu”.
	33	</para>
	34
	35	<para>
	36	With Amtk, menus, toolbars or other objects like
	37	<link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link> are created
	38	programmatically (not with a *.ui file), but with convenient APIs. The support
	39	for an XML format will maybe be added in the future, contributions welcome.
	40	</para>
	41
	42	<refsect1>
	43	<title>General advantages</title>
	44	<itemizedlist>
	45	<listitem>
	46	<para>
	47	Primarily, encoding the information about an action only once, to create
	48	various objects such as a menu item, a toolbar item, a
	49	<link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>, etc.
	50	The information needed about an action: a label (i.e. a short
	51	description), possibly an icon, a tooltip (i.e. a longer description)
	52	and keyboard shortcuts. This is implemented by
	53	<link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
	54	<link linkend="AmtkFactory">AmtkFactory</link> functions to create
	55	various objects.
	56	</para>
	57	<para>
	58	This also has the nice benefit that all the information about an action
	59	is centralized in only one place, to keep related information close
	60	together. This permits to more easily catch inconsistencies.
	61	</para>
	62	</listitem>
	63	<listitem>
	64	<para>
	65	Amtk has been designed to be able to share
	66	<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
	67	translations); this is a bit similar to
	68	<link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
	69	work that an application (and translators) need to do. As a result the
	70	library can provide a higher-level API.
	71	</para>
	72	</listitem>
	73	</itemizedlist>
	74	</refsect1>
	75
	76	<refsect1>
	77	<title>Advantages for a traditional UI</title>
	78	<itemizedlist>
	79	<listitem>
	80	<para>
	81	When writing an XML file to create a <link linkend="GMenu">GMenu</link>
	82	with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
	83	(see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
	84	the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
	85	not a toolbar. It is not a good programming practice to duplicate the
	86	information. With Amtk the information is encoded just once, in
	87	<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s, and menu and
	88	toolbar items are created with <link linkend="AmtkFactory">AmtkFactory</link>
	89	which uses the information provided by the
	90	<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s.
	91	</para>
	92	</listitem>
	93	<listitem>
	94	<para>
	95	Something that is not possible to do with the support of
	96	<link linkend="GMenu">GMenu</link> in GTK, that Amtk solves when using
	97	<link linkend="GtkMenuItem">GtkMenuItem</link>'s: when a
	98	<link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g. when
	99	the mouse hovers it), showing a longer description in the
	100	<link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
	101	<link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
	102	makes the UI better self-discoverable, to improve the usability.
	103	</para>
	104	</listitem>
	105	<listitem>
	106	<para>
	107	Related to the previous point: having a
	108	<link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
	109	in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
	110	when a menu item is selected. This is implemented by
	111	<link linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
	112	</para>
	113	</listitem>
	114	</itemizedlist>
	115	</refsect1>
	116
	117	<refsect1>
	118	<title>Sanity checks</title>
	119	<para>
	120	Amtk has several functions to do various sanity checks. They normally don't
	121	impact too much the performances, so it is recommended to always run them,
	122	although they could be disabled on production. The functions:
	123	</para>
	124	<itemizedlist>
	125	<listitem>
	126	<para>
	127	<link linkend="amtk-action-map-add-action-entries-check-dups">amtk_action_map_add_action_entries_check_dups()</link>
	128	</para>
	129	</listitem>
	130	<listitem>
	131	<para>
	132	<link linkend="amtk-action-info-store-check-all-used">amtk_action_info_store_check_all_used()</link>
	133	</para>
	134	</listitem>
	135	<listitem>
	136	<para>
	137	Another sanity check, but which cannot be disabled: the
	138	<link linkend="AmtkActionInfoCentralStore">AmtkActionInfoCentralStore</link>
	139	checks that each <link linkend="AmtkActionInfo">AmtkActionInfo</link>
	140	has a unique action name. Which means that
	141	<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s provided by a
	142	library must be namespaced.
	143	</para>
	144	</listitem>
	145	</itemizedlist>
	146	</refsect1>
	147
	148	<refsect1>
	149	<title>GTK dependency</title>
	150	<para>
	151	Amtk &package_api_version; depends on GTK 3.
	152	</para>
	153	</refsect1>
	154
	155	<refsect1>
	156	<title>pkg-config name</title>
	157	<para>
	158	For Amtk &package_api_version;, the pkg-config name is:
	159	<code>amtk-&package_api_version;</code>
	160	</para>
	161	<para>
	162	To compile a program that uses Amtk &package_api_version;, you can for
	163	example use the following command:
	164	</para>
	165	<para>
	166	<code>$ gcc hello.c `pkg-config --cflags --libs amtk-&package_api_version;` -o hello</code>
	167	</para>
	168	</refsect1>
	169	</refentry>

-170

~~docs/reference/amtk-intro.xml.in~~ less more

0		<?xml version="1.0"?>
1		<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
2		"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
3		[
4		<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5		<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
6		%gtkdocentities;
7		]>
8
9		<refentry id="amtk-intro">
10		<refmeta>
11		<refentrytitle>Amtk Introduction</refentrytitle>
12		</refmeta>
13
14		<refnamediv>
15		<refname>Amtk Introduction</refname>
16		<refpurpose>
17		Introduction to the Actions, Menus and Toolbars Kit for GTK applications.
18		</refpurpose>
19		</refnamediv>
20
21		<para>
22		Amtk is the acronym for “Actions, Menus and Toolbars Kit”. Amtk has been
23		initially created as a basic <link linkend="GtkUIManager">GtkUIManager</link>
24		replacement based on <link linkend="GAction">GAction</link>.
25		<link linkend="GtkUIManager">GtkUIManager</link> has been deprecated in
26		GTK 3 (and removed in GTK 4), without a good replacement for
27		applications that want to keep a traditional UI (with a
28		<link linkend="GtkMenuBar">GtkMenuBar</link>, a
29		<link linkend="GtkToolbar">GtkToolbar</link> and a
30		<link linkend="GtkStatusbar">GtkStatusbar</link>). Amtk is now suitable for
31		both a traditional UI and for a new UI with a
32		<link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “hamburger menu”.
33		</para>
34
35		<para>
36		With Amtk, menus, toolbars or other objects like
37		<link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link> are created
38		programmatically (not with a *.ui file), but with convenient APIs. The support
39		for an XML format will maybe be added in the future, contributions welcome.
40		</para>
41
42		<refsect1>
43		<title>General advantages</title>
44		<itemizedlist>
45		<listitem>
46		<para>
47		Primarily, encoding the information about an action only once, to create
48		various objects such as a menu item, a toolbar item, a
49		<link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>, etc.
50		The information needed about an action: a label (i.e. a short
51		description), possibly an icon, a tooltip (i.e. a longer description)
52		and keyboard shortcuts. This is implemented by
53		<link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
54		<link linkend="AmtkFactory">AmtkFactory</link> functions to create
55		various objects.
56		</para>
57		<para>
58		This also has the nice benefit that all the information about an action
59		is centralized in only one place, to keep related information close
60		together. This permits to more easily catch inconsistencies.
61		</para>
62		</listitem>
63		<listitem>
64		<para>
65		Amtk has been designed to be able to share
66		<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
67		translations); this is a bit similar to
68		<link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
69		work that an application (and translators) need to do. As a result the
70		library can provide a higher-level API.
71		</para>
72		</listitem>
73		</itemizedlist>
74		</refsect1>
75
76		<refsect1>
77		<title>Advantages for a traditional UI</title>
78		<itemizedlist>
79		<listitem>
80		<para>
81		When writing an XML file to create a <link linkend="GMenu">GMenu</link>
82		with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
83		(see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
84		the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
85		not a toolbar. It is not a good programming practice to duplicate the
86		information. With Amtk the information is encoded just once, in
87		<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s, and menu and
88		toolbar items are created with <link linkend="AmtkFactory">AmtkFactory</link>
89		which uses the information provided by the
90		<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s.
91		</para>
92		</listitem>
93		<listitem>
94		<para>
95		Something that is not possible to do with the support of
96		<link linkend="GMenu">GMenu</link> in GTK, that Amtk solves when using
97		<link linkend="GtkMenuItem">GtkMenuItem</link>'s: when a
98		<link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g. when
99		the mouse hovers it), showing a longer description in the
100		<link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
101		<link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
102		makes the UI better self-discoverable, to improve the usability.
103		</para>
104		</listitem>
105		<listitem>
106		<para>
107		Related to the previous point: having a
108		<link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
109		in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
110		when a menu item is selected. This is implemented by
111		<link linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
112		</para>
113		</listitem>
114		</itemizedlist>
115		</refsect1>
116
117		<refsect1>
118		<title>Sanity checks</title>
119		<para>
120		Amtk has several functions to do various sanity checks. They normally don't
121		impact too much the performances, so it is recommended to always run them,
122		although they could be disabled on production. The functions:
123		</para>
124		<itemizedlist>
125		<listitem>
126		<para>
127		<link linkend="amtk-action-map-add-action-entries-check-dups">amtk_action_map_add_action_entries_check_dups()</link>
128		</para>
129		</listitem>
130		<listitem>
131		<para>
132		<link linkend="amtk-action-info-store-check-all-used">amtk_action_info_store_check_all_used()</link>
133		</para>
134		</listitem>
135		<listitem>
136		<para>
137		Another sanity check, but which cannot be disabled: the
138		<link linkend="AmtkActionInfoCentralStore">AmtkActionInfoCentralStore</link>
139		checks that each <link linkend="AmtkActionInfo">AmtkActionInfo</link>
140		has a unique action name. Which means that
141		<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s provided by a
142		library must be namespaced.
143		</para>
144		</listitem>
145		</itemizedlist>
146		</refsect1>
147
148		<refsect1>
149		<title>GTK dependency</title>
150		<para>
151		Amtk @AMTK_API_VERSION@ depends on GTK 3.
152		</para>
153		</refsect1>
154
155		<refsect1>
156		<title>pkg-config name</title>
157		<para>
158		For Amtk @AMTK_API_VERSION@, the pkg-config name is:
159		<code>amtk-@AMTK_API_VERSION@</code>
160		</para>
161		<para>
162		To compile a program that uses Amtk @AMTK_API_VERSION@, you can for
163		example use the following command:
164		</para>
165		<para>
166		<code>$ gcc hello.c `pkg-config --cflags --libs amtk-@AMTK_API_VERSION@` -o hello</code>
167		</para>
168		</refsect1>
169		</refentry>

+182

-0

docs/reference/amtk-sections.txt less more

	0	<INCLUDE>amtk/amtk.h</INCLUDE>
	1
	2	<SECTION>
	3	<FILE>amtk-init</FILE>
	4	<TITLE>Amtk Initialization and Finalization</TITLE>
	5	amtk_init
	6	amtk_finalize
	7	</SECTION>
	8
	9	<SECTION>
	10	<FILE>amtk-application-window</FILE>
	11	AmtkApplicationWindow
	12	amtk_application_window_get_from_gtk_application_window
	13	amtk_application_window_get_application_window
	14	amtk_application_window_get_statusbar
	15	amtk_application_window_set_statusbar
	16	amtk_application_window_connect_menu_to_statusbar
	17	amtk_application_window_connect_recent_chooser_menu_to_statusbar
	18	amtk_application_window_create_open_recent_menu
	19	amtk_application_window_create_open_recent_menu_item
	20	<SUBSECTION Standard>
	21	AMTK_APPLICATION_WINDOW
	22	AMTK_APPLICATION_WINDOW_CLASS
	23	AMTK_APPLICATION_WINDOW_GET_CLASS
	24	AMTK_IS_APPLICATION_WINDOW
	25	AMTK_IS_APPLICATION_WINDOW_CLASS
	26	AMTK_TYPE_APPLICATION_WINDOW
	27	AmtkApplicationWindowClass
	28	AmtkApplicationWindowPrivate
	29	amtk_application_window_get_type
	30	</SECTION>
	31
	32	<SECTION>
	33	<FILE>amtk-action-info</FILE>
	34	AmtkActionInfo
	35	AmtkActionInfoEntry
	36	amtk_action_info_new
	37	amtk_action_info_new_from_entry
	38	amtk_action_info_ref
	39	amtk_action_info_unref
	40	amtk_action_info_copy
	41	amtk_action_info_get_action_name
	42	amtk_action_info_set_action_name
	43	amtk_action_info_get_icon_name
	44	amtk_action_info_set_icon_name
	45	amtk_action_info_get_label
	46	amtk_action_info_set_label
	47	amtk_action_info_get_tooltip
	48	amtk_action_info_set_tooltip
	49	amtk_action_info_get_accels
	50	amtk_action_info_set_accels
	51	amtk_action_info_mark_as_used
	52	amtk_action_info_has_been_used
	53	<SUBSECTION Standard>
	54	amtk_action_info_get_type
	55	AMTK_TYPE_ACTION_INFO
	56	</SECTION>
	57
	58	<SECTION>
	59	<FILE>amtk-action-info-store</FILE>
	60	AmtkActionInfoStore
	61	amtk_action_info_store_new
	62	amtk_action_info_store_add
	63	amtk_action_info_store_add_entries
	64	amtk_action_info_store_lookup
	65	amtk_action_info_store_set_all_accels_to_app
	66	amtk_action_info_store_check_all_used
	67	<SUBSECTION Standard>
	68	AMTK_ACTION_INFO_STORE
	69	AMTK_ACTION_INFO_STORE_CLASS
	70	AMTK_ACTION_INFO_STORE_GET_CLASS
	71	AMTK_IS_ACTION_INFO_STORE
	72	AMTK_IS_ACTION_INFO_STORE_CLASS
	73	AMTK_TYPE_ACTION_INFO_STORE
	74	AmtkActionInfoStoreClass
	75	AmtkActionInfoStorePrivate
	76	amtk_action_info_store_get_type
	77	</SECTION>
	78
	79	<SECTION>
	80	<FILE>amtk-action-info-central-store</FILE>
	81	AmtkActionInfoCentralStore
	82	amtk_action_info_central_store_get_singleton
	83	amtk_action_info_central_store_lookup
	84	<SUBSECTION Standard>
	85	AMTK_ACTION_INFO_CENTRAL_STORE
	86	AMTK_ACTION_INFO_CENTRAL_STORE_CLASS
	87	AMTK_ACTION_INFO_CENTRAL_STORE_GET_CLASS
	88	AMTK_IS_ACTION_INFO_CENTRAL_STORE
	89	AMTK_IS_ACTION_INFO_CENTRAL_STORE_CLASS
	90	AMTK_TYPE_ACTION_INFO_CENTRAL_STORE
	91	AmtkActionInfoCentralStoreClass
	92	AmtkActionInfoCentralStorePrivate
	93	amtk_action_info_central_store_get_type
	94	</SECTION>
	95
	96	<SECTION>
	97	<FILE>amtk-action-map</FILE>
	98	amtk_action_map_add_action_entries_check_dups
	99	</SECTION>
	100
	101	<SECTION>
	102	<FILE>amtk-factory</FILE>
	103	AmtkFactory
	104	AmtkFactoryFlags
	105	amtk_factory_new
	106	amtk_factory_new_with_default_application
	107	amtk_factory_get_application
	108	amtk_factory_get_default_flags
	109	amtk_factory_set_default_flags
	110	amtk_factory_create_menu_item
	111	amtk_factory_create_menu_item_full
	112	amtk_factory_create_check_menu_item
	113	amtk_factory_create_check_menu_item_full
	114	amtk_factory_create_simple_menu
	115	amtk_factory_create_simple_menu_full
	116	amtk_factory_create_gmenu_item
	117	amtk_factory_create_gmenu_item_full
	118	amtk_factory_create_tool_button
	119	amtk_factory_create_tool_button_full
	120	amtk_factory_create_menu_tool_button
	121	amtk_factory_create_menu_tool_button_full
	122	amtk_factory_create_shortcut
	123	amtk_factory_create_shortcut_full
	124	<SUBSECTION Standard>
	125	AMTK_FACTORY
	126	AMTK_FACTORY_CLASS
	127	AMTK_FACTORY_GET_CLASS
	128	AMTK_IS_FACTORY
	129	AMTK_IS_FACTORY_CLASS
	130	AMTK_TYPE_FACTORY
	131	AmtkFactoryClass
	132	AmtkFactoryPrivate
	133	amtk_factory_get_type
	134	AMTK_TYPE_FACTORY_FLAGS
	135	amtk_factory_flags_get_type
	136	</SECTION>
	137
	138	<SECTION>
	139	<FILE>amtk-gmenu</FILE>
	140	amtk_gmenu_append_item
	141	amtk_gmenu_append_section
	142	</SECTION>
	143
	144	<SECTION>
	145	<FILE>amtk-menu-item</FILE>
	146	amtk_menu_item_get_long_description
	147	amtk_menu_item_set_long_description
	148	amtk_menu_item_set_icon_name
	149	</SECTION>
	150
	151	<SECTION>
	152	<FILE>amtk-menu-shell</FILE>
	153	AmtkMenuShell
	154	amtk_menu_shell_get_from_gtk_menu_shell
	155	amtk_menu_shell_get_menu_shell
	156	<SUBSECTION Standard>
	157	AMTK_IS_MENU_SHELL
	158	AMTK_IS_MENU_SHELL_CLASS
	159	AMTK_MENU_SHELL
	160	AMTK_MENU_SHELL_CLASS
	161	AMTK_MENU_SHELL_GET_CLASS
	162	AMTK_TYPE_MENU_SHELL
	163	AmtkMenuShellClass
	164	AmtkMenuShellPrivate
	165	amtk_menu_shell_get_type
	166	</SECTION>
	167
	168	<SECTION>
	169	<FILE>amtk-shortcuts</FILE>
	170	amtk_shortcuts_window_new
	171	amtk_shortcuts_section_new
	172	amtk_shortcuts_group_new
	173	</SECTION>
	174
	175	<SECTION>
	176	<FILE>amtk-utils</FILE>
	177	amtk_utils_remove_mnemonic
	178	amtk_utils_recent_chooser_menu_get_item_uri
	179	amtk_utils_bind_g_action_to_gtk_action
	180	amtk_utils_create_gtk_action
	181	</SECTION>

+35

-0

docs/reference/meson.build less more

	0	subdir('xml')
	1
	2	configure_file(
	3	input: 'amtk-sections.txt',
	4	output: 'amtk-@0@-sections.txt'.format(AMTK_API_VERSION),
	5	copy: true
	6	)
	7
	8	gtkdoc_module_name = 'amtk-@0@'.format(AMTK_API_VERSION)
	9	html_dir = get_option('prefix') / GNOME.gtkdoc_html_dir(gtkdoc_module_name)
	10
	11	glib_docpath = dependency('glib-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/glib'
	12	gobject_docpath = dependency('gobject-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gobject'
	13	gio_docpath = dependency('gio-2.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gio'
	14	gtk_docpath = dependency('gtk+-3.0').get_pkgconfig_variable('prefix') / 'share/gtk-doc/html/gtk3'
	15
	16	GNOME.gtkdoc(
	17	gtkdoc_module_name,
	18	main_xml: 'amtk-docs.xml',
	19	src_dir: include_directories('../../amtk/'),
	20	dependencies: AMTK_LIB_DEP,
	21	scan_args: ['--rebuild-types'],
	22	gobject_typesfile: 'amtk-@0@.types'.format(AMTK_API_VERSION),
	23	fixxref_args: [
	24	'--html-dir=@0@'.format(html_dir),
	25	'--extra-dir=@0@'.format(glib_docpath),
	26	'--extra-dir=@0@'.format(gobject_docpath),
	27	'--extra-dir=@0@'.format(gio_docpath),
	28	'--extra-dir=@0@'.format(gtk_docpath)
	29	],
	30	content_files: [
	31	'amtk-intro.xml',
	32	],
	33	install: true
	34	)

-0

docs/reference/xml/gtkdocentities.ent.in less more

	0	<!ENTITY package_string "@PACKAGE_STRING@">
	1	<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

+11

-0

docs/reference/xml/meson.build less more

	0	gtkdocentities_conf_data = configuration_data()
	1	gtkdocentities_conf_data.set('PACKAGE_STRING', 'Amtk @0@'.format(meson.project_version()))
	2	gtkdocentities_conf_data.set('PACKAGE_API_VERSION', AMTK_API_VERSION)
	3
	4	gtkdocentities_filename = 'gtkdocentities.ent'
	5
	6	configure_file(
	7	input: gtkdocentities_filename + '.in',
	8	output: gtkdocentities_filename,
	9	configuration: gtkdocentities_conf_data
	10	)

-4

meson.build less more

137	137	subdir('tests')
138	138	subdir('testsuite')
139	139
140		#if get_option('gtk_doc')
141		# subdir('docs/reference')
142		#endif
	140	if get_option('gtk_doc')
	141	subdir('docs/reference')
	142	endif
143	143
144	144	summary('API version', AMTK_API_VERSION)
145	145	summary('Prefix', get_option('prefix'))
146		#summary('API documentation', get_option('gtk_doc'))
	146	summary('API documentation', get_option('gtk_doc'))

-0

meson_options.txt less more

	0	option(
	1	'gtk_doc',
	2	type: 'boolean', value: false,
	3	description: 'Build API reference (requires gtk-doc)'
	4	)