GNOME.org
 

[gtk-mac-integration] Update documents for current version of Gtk-Docs.

commit 8645c5f7c36d3f60f39871b9ff8aee56c0a24553
Author: John Ralls <jralls ceridwen us>
Date:   Mon Feb 23 10:41:41 2015 -0800

    Update documents for current version of Gtk-Docs.

 docs/reference/Makefile.am                         |   60 ++++-----
 ...tion-docs.sgml => gtk-mac-integration-docs.xml} |   16 ++-
 docs/reference/gtk-mac-integration-sections.txt    |   44 ++++++
 docs/reference/gtk-mac-integration.types           |    1 +
 src/gtkosxapplication.c                            |  142 +++++++++++---------
 5 files changed, 161 insertions(+), 102 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 2877c4a..55d4c7f 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -1,8 +1,3 @@
-## Process this file with automake to produce Makefile.in
-
-# We require automake 1.6 at least.
-AUTOMAKE_OPTIONS = 1.6
-
 # This is a blank Makefile.am for using gtk-doc.
 # Copy this to your project's API docs directory and modify the variables to
 # suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
@@ -12,16 +7,15 @@ AUTOMAKE_OPTIONS = 1.6
 DOC_MODULE=gtk-mac-integration
 
 # Uncomment for versioned docs and specify the version of the module, e.g. '2'.
-DOC_MODULE_VERSION=0.9
+#DOC_MODULE_VERSION=2
 
+# The top-level XML file (SGML in the past). You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
 
-# The top-level SGML file. You can change this if you want to.
-DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
-
-# The directory containing the source code. Relative to $(srcdir).
-# gtk-doc will search all .c & .h files beneath here for inline comments
-# documenting the functions and macros.
-# e.g. DOC_SOURCE_DIR=../../../gtk
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
 DOC_SOURCE_DIR=$(top_srcdir)/src
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
@@ -29,11 +23,11 @@ SCANGOBJ_OPTIONS=
 
 # Extra options to supply to gtkdoc-scan.
 # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=--rebuild-types --rebuild-sections
+SCAN_OPTIONS=
 
 # Extra options to supply to gtkdoc-mkdb.
-# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
-MKDB_OPTIONS=--sgml-mode --output-format=xml
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
 
 # Extra options to supply to gtkdoc-mktmpl
 # e.g. MKTMPL_OPTIONS=--only-section-tmpl
@@ -52,8 +46,12 @@ FIXXREF_OPTIONS=--extra-dir=html
 HFILE_GLOB=$(top_srcdir)/src/*.h
 CFILE_GLOB=$(top_srcdir)/src/*.c
 
-# Header files to ignore when scanning.
-# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
 IGNORE_HFILES=                         \
        gtk-mac-integration.h           \
        gtk-mac-bundle.h                \
@@ -79,7 +77,6 @@ HTML_IMAGES=
 content_files=
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
-# These files must be listed here *and* in content_files
 # e.g. expand_content_files=running.sgml
 expand_content_files=
 
@@ -88,21 +85,20 @@ expand_content_files=
 # signals and properties.
 # e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
 # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-GTKDOC_CFLAGS = $(GLIB_CFLAGS)
-GTKDOC_LIBS = $(top_builddir)/src/libgtkmacintegration- GTK_MAC_INTEGRATION_LIB_SUFFIX@.la -lgobject-2.0
+GTKDOC_CFLAGS=$(GLIB_CFLAGS)
+GTKDOC_LIBS=$(top_builddir)/src/libgtkmacintegration- GTK_MAC_INTEGRATION_LIB_SUFFIX@.la -lgobject-2.0
 DYLD_LOAD_PATH=$(top_builddir)/src/.libs
+
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
 
-# Other files to distribute
-# e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST +=
-
-# Files not to distribute
-# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
-# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
-#DISTCLEANFILES +=
-
-# Comment this out if you want your docs-status tested during 'make check'
-#TESTS = $(GTKDOC_CHECK)
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
 
+-include $(top_srcdir)/git.mk
diff --git a/docs/reference/gtk-mac-integration-docs.sgml b/docs/reference/gtk-mac-integration-docs.xml
similarity index 64%
rename from docs/reference/gtk-mac-integration-docs.sgml
rename to docs/reference/gtk-mac-integration-docs.xml
index 626b78f..48b47bb 100644
--- a/docs/reference/gtk-mac-integration-docs.sgml
+++ b/docs/reference/gtk-mac-integration-docs.xml
@@ -6,17 +6,19 @@
 ]>
 <book id="index">
   <bookinfo>
-    <title>Gtk-OSX Integration Reference Manual</title>
+    <title>gtk-mac-integration Reference Manual</title>
     <releaseinfo>
-      For <b>gtk-mac-integration 2.0.6</b><br/>
+      for gtk-mac-integration 2.0.8.
       The latest version of this documentation can be found on-line at
-      <ulink role="online-location" 
url="http://gtk-osx.sourceforge.net/gtk-mac-integration/index.htmL";>http://gtk-osx.sourceforge.net/gtk-mac-integration/</ulink>.
+      <ulink role="online-location" 
url="http://gtk-osx.sourceforge.net/gtk-mac-integration/index.html";>http://gtk-osx.sourceforge.net/gtk-mac-integration/</ulink>.
     </releaseinfo>
   </bookinfo>
 
   <chapter>
-    <title>GtkOSXApplication Reference</title>
-        <xi:include href="xml/gtkosxapplication.xml"/>
+    <title>GtkosxApplication Reference</title>
+        <xi:include href="xml/gtkosx-image.xml"/>
+    <xi:include href="xml/gtkosxapplication.xml"/>
+
   </chapter>
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
@@ -26,6 +28,10 @@
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
   </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/gtk-mac-integration-sections.txt b/docs/reference/gtk-mac-integration-sections.txt
new file mode 100644
index 0000000..0b627d1
--- /dev/null
+++ b/docs/reference/gtk-mac-integration-sections.txt
@@ -0,0 +1,44 @@
+<SECTION>
+<FILE>gtkosxapplication</FILE>
+<TITLE>GtkosxApplication</TITLE>
+GtkosxApplicationMenuGroup
+gtkosx_application_get
+gtkosx_application_ready
+gtkosx_application_set_use_quartz_accelerators
+gtkosx_application_use_quartz_accelerators
+gtkosx_application_set_menu_bar
+gtkosx_application_sync_menubar
+gtkosx_application_insert_app_menu_item
+gtkosx_application_set_window_menu
+gtkosx_application_set_help_menu
+GtkosxApplicationAttentionType
+GTKOSX_TYPE_APPLICATION_ATTENTION_TYPE
+gtkosx_application_set_dock_menu
+gtkosx_application_set_dock_icon_pixbuf
+gtkosx_application_set_dock_icon_resource
+gtkosx_application_attention_request
+gtkosx_application_cancel_attention_request
+gtkosx_application_get_bundle_path
+gtkosx_application_get_resource_path
+gtkosx_application_get_executable_path
+gtkosx_application_get_bundle_id
+gtkosx_application_get_bundle_info
+<SUBSECTION Standard>
+GTKOSX_APPLICATION
+GTKOSX_APPLICATION_CLASS
+GTKOSX_APPLICATION_GET_CLASS
+GTKOSX_IS_APPLICATION
+GTKOSX_IS_APPLICATION_CLASS
+GTKOSX_TYPE_APPLICATION
+GtkosxApplication
+GtkosxApplicationClass
+GtkosxApplicationPrivate
+gtkosx_application_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkosx-image</FILE>
+nsimage_from_resource
+nsimage_from_pixbuf
+</SECTION>
+
diff --git a/docs/reference/gtk-mac-integration.types b/docs/reference/gtk-mac-integration.types
new file mode 100644
index 0000000..76ecff8
--- /dev/null
+++ b/docs/reference/gtk-mac-integration.types
@@ -0,0 +1 @@
+gtkosx_application_get_type
diff --git a/src/gtkosxapplication.c b/src/gtkosxapplication.c
index 1892697..c31cf7b 100644
--- a/src/gtkosxapplication.c
+++ b/src/gtkosxapplication.c
@@ -29,31 +29,39 @@
 #define DEBUG(format, ...)
 /**
  * SECTION:gtkosxapplication
- * @short_description: Base class for OSX integration
+ * @short_description: Base class for OS X integration
  * @title: GtkosxApplication
  * @include: gtkosxapplication.h
  *
  * Exposes to the Gtk+ program important functions of
- * OSX's NSApplication class for use by Gtk+ applications running with
+ * OS X's NSApplication class for use by Gtk+ applications running with
  * the quartz Gdk backend and provides addtional functions for
- * integrating a Gtk+ program into the OSX user environment.
+ * integrating a Gtk+ program into the OS X user environment.
  *
  * Using GtkosxApplication is pretty simple.
  * First, create an instance at startup:
  *
- * |[GtkosxApplication *theApp = g_object_new(GTKOSX_TYPE_APPLICATION, NULL);]|
+ * |[<!-- language="C" -->
+ * GtkosxApplication *theApp = g_object_new(GTKOSX_TYPE_APPLICATION, NULL);
+ * ]|
  *
  * Do this early in your program, shortly after you run
- * |[gtk_init()]|. Don't forget to guard it, and all other calls into
- * the library, with |[#ifdef MAC_INTEGRATION]|. You don't want your
- * Linux users' builds failing because of this.  The application
- * object is a singleton, so you can call g_object_new as often as you
- * like. You'll always get the same pointer back. There's no need to
- * pass it around as an argument. Do note that all of the
- * GtkosxApplication functions take theApp as an argument, even if
- * they don't use it. This seems silly in C, and perhaps it is, but
- * it's needed to make the Python binding logic recognize that they're
- * class methods.
+ * |[
+ * gtk_init()
+ * ]|
+ * Don't forget to guard it, and all other calls into the library, with
+ * |[
+ * #ifdef MAC_INTEGRATION
+ * ]|
+ *
+ * You don't want your Linux users' builds failing because of this.
+ * The application object is a singleton, so you can call g_object_new
+ * as often as you like. You'll always get the same pointer
+ * back. There's no need to pass it around as an argument. Do note
+ * that all of the GtkosxApplication functions take theApp as an
+ * argument, even if they don't use it. This seems silly in C, and
+ * perhaps it is, but it's needed to make the Python binding logic
+ * recognize that they're class methods.
  *
  * Just having the application object created will get you some
  * benefits, like having the Quit menu item in the dock menu work. But
@@ -68,9 +76,8 @@
  * and call gtkosx_application_set_main_menu(). Here's an example with
  * GtkBuilder:
  *
- * <example>
- * <title>Setting the MenuBar</title>
- * <programlisting>
+ * ## Setting the MenuBar
+ * |[<!-- language="C" -->
  *   GtkUIManager *mgr = gtk_ui_manager_new();
  *   GtkosxApplication *theApp = g_object_new(GTKOSX_TYPE_APPLICATION, NULL);
  *   ...
@@ -79,31 +86,26 @@
  *   menubar = gtk_ui_manager_get_widget(mgr, "/menubar");
  *   gtk_widget_hide (menubar);
  *   gtkosx_application_set_menu_bar(theApp, GTK_MENU_SHELL(menubar));
- * </programlisting>
- * </example>
+ * ]|
  *
  * There are a couple of wrinkles, though, if you use
  * accelerators. First off, there are two event paths for
- * accelerators: Quartz, where the keystroke is processed by OSX and
- * the menu item action event is placed on the event queue by OSX, or
+ * accelerators: Quartz, where the keystroke is processed by OS X and
+ * the menu item action event is placed on the event queue by OS X, or
  * Gtk, where the accelerator key event is passed through to Gtk to
  * recognize. This is controlled by
  * gtkosx_application_set_use_quartz_accelerators() (you can test the
  * value with gtkosx_application_use_quartz_accelerators()), and the
  * default is to use Quartz handling. This has two advantages:
- * <itemizedlist>
- * <listitem><para>It works without any extra steps</para></listitem>
- * <listitem><para>
- * It changes stock accelerators (like Ctrl-O for open file) to
- * the stock OSX keyEquivalent (Cmd-O in that case).
- * </para></listitem>
- * </itemizedlist>
- * If you need to use Gtk+ keyboard accelerator handling <emphasis>and</emphasis>
+ * - It works without any extra steps
+ * - It changes stock accelerators (like Ctrl-O for open file) to
+ * the stock OS X keyEquivalent (Cmd-O in that case).
+ *
+ * If you need to use Gtk+ keyboard accelerator handling *and*
  * you're using GtkMenuItems instead of GtkActions, you'll need to
  * connect a special handler as shown in the following example:
- * <example>
- * <title>Enabling Accelerators on Hidden Menus</title>
- * <programlisting>
+ * ## Enabling Accelerators on Hidden Menus
+ * |[<!-- language="C" -->
  * static gboolean
  * can_activate_cb(GtkWidget* widget, guint signal_id, gpointer data)
  * {
@@ -112,29 +114,28 @@
  * ...
  *   g_signal_connect(menubar, "can-activate-accel",
  *                    G_CALLBACK(can_activate_cb), NULL);
- * </programlisting>
- * </example>
+ * ]|
  *
  * The next task to make your application appear more normal for Mac
  * users is to move some menu items from their normal Gtk locations to
  * the so-called "App" menu. That's the menu all the way at the left
  * of the menubar that has the currently-running application's
  * name. There are 3 menu items that normally go there:
- * <itemizedlist>
- * <listitem><para>Help|About</para></listitem>
- * <listitem><para>Edit|Preferences</para></listitem>
- * <listitem><para>File|Quit</para></listitem>
- * </itemizedlist>
- * File|Quit is a special case, because OSX handles it itself and
+ * - Help|About
+ * - Edit|Preferences
+ * - File|Quit
+ *
+ * File|Quit is a special case, because OS X handles it itself and
  * automatically includes it, so the only thing you need do is hide it
  * on the File menu so that it doesn't show up twice:
- * |[gtk_widget_hide(GTK_WIDGET(file_quit_menu_item));]|
+ * |[
+ * gtk_widget_hide(GTK_WIDGET(file_quit_menu_item));
+ * ]|
  * The other two must be moved in code, and there are two functions
  * for doing that. The first one creates "goups", which is just an
  * easy way to manage separators, and the second adds the actual menu
  * items to the groups. Here's an example:
- * <example>
- * <programlisting>
+ * |[
  *  GtkosxApplicationMenuGroup *group;
  *  GtkMenuItem *about_item, *preferences_item;
  *  about_item = gtk_ui_manager_get_widget(mgr, "/menubar/Help/About");
@@ -147,12 +148,13 @@
  *  group = gtkosx_application_add_app_menu_group (theApp);
  *  gtkosx_application_add_app_menu_item  (theApp, group,
  *                                         GTK_MENU_ITEM (preferences_item));
- * </programlisting>
- * </example>
+ * ]|
  * Once we have everything set up for as many windows as we're going
- * to open before we call gtk_main_loop(), we need to tell OSX that
+ * to open before we call gtk_main_loop(), we need to tell OS X that
  * we're ready:
- * |[gtkosx_application_ready(theApp);]|
+ * |[
+ * gtkosx_application_ready(theApp);
+ * ]|
  *
  * If you add other windows later, you must do everything above for
  * each one's menubar. Most of the time the internal notifictations
@@ -160,10 +162,12 @@
  * in sync. However, if you at any time disconnect or block signals
  * and change the menu (perhaps because of a context change within a
  * window, as with changing pages in a GtkNotebook) you need to call
- * |[gtkosx_application_sync_menubar(theApp)]|
+ * |[
+ * gtkosx_application_sync_menubar(theApp)
+ * ]|
  *
- *
- * * The dock is that bar of icons that normally lives at the bottom of
+ * ## Dock Support
+ * The dock is that bar of icons that normally lives at the bottom of
  * the display on a Mac (though it can be moved to one of the other
  * sides; this author likes his on the left, which is where it was
  * originally on a NeXT). Each running application has a "dock tile",
@@ -178,24 +182,29 @@
  * task so that the user will know that it's finished if she's
  * switched to another application while she waits for yours.
  * They're all pretty simple, so you can just read the details below.
+ * - gtkosx_application_set_doc_menu()
+ * - gtkosx_application_set_doc_icon_pixbuf()
+ * - gtkosx_application_set_dock_icon_resource()
+ * - gtkosx_application_attention_request()
+ * - gtkosx_application_cancel_attention_request()
  *
- *
- * * The last feature to which GtkosxApplication provides an interface
- * is the bundle. Normally in OSX, graphical applications are packaged
+ * ## Bundle Support
+ * The last feature to which GtkosxApplication provides an interface
+ * is the bundle. Normally in OS X, graphical applications are packaged
  * along with their non-standard dependencies and their resources
  * (graphical elements, translations, and such) in special directory
  * structures called "bundles". To easily package your Gtk+
  * application, have a look at gtk-mac-bundler, also available from
  * the Gtk-OSX project.
  *
- * OSX provides a variety of functions pertaining to bundles, most of which are not likely to interest 
someone porting a Gtk+ application. GtkosxApplication has wrapped a few that might be:
- * <itemizedlist>
- * <listitem><para>gtkosx_application_get_bundle_path()</para></listitem>
- * <listitem><para>gtkosx_application_get_resource_path()</para></listitem>
- * <listitem><para>gtkosx_application_get_executable_path()</para></listitem>
- * <listitem><para>gtkosx_application_get_bundle_id()</para></listitem>
- * <listitem><para>gtkosx_application_get_bundle_info()</para></listitem>
- * </itemizedlist>
+ * OS X provides a variety of functions pertaining to bundles, most of
+ * which are not likely to interest someone porting a Gtk+
+ * application. GtkosxApplication has wrapped a few that might be:
+ * - gtkosx_application_get_bundle_path()
+ * - gtkosx_application_get_resource_path()
+ * - gtkosx_application_get_executable_path()
+ * - gtkosx_application_get_bundle_id()
+ * - gtkosx_application_get_bundle_info()
  *
  * The first three just get a UTF8-encoded path. An interesting note
  * is that they'll return the path to the executable or the folder
@@ -207,7 +216,9 @@
  * opening the bundle. (In other words, even if you have your
  * application installed in Foo.app, if you launch it from the command
  * line as
- *|[$ Foo.app/Contents/MacOS/Foo]|
+ * |[
+ * $ Foo.app/Contents/MacOS/Foo
+ * ]|
  * the Info.plist won't have been opened and
  * gtkosx_application_get_bundle_id() will return "". Of course, it
  * will also return "" if you didn't set %CFBundleIdentifier in the
@@ -218,12 +229,13 @@
  * as long as that value is a string. If it isn't, then the function
  * returns a null string ("").
  *
+ * ## Notifications
  * Finally, notice the signals. These are emitted in response to the
- * indicated OSX notifications. Except for
+ * indicated OS X notifications. Except for
  * #GtkosxApplication::NSApplicationBlockTermination, most programs
  * won't need to do anything with
  * them. #GtkosxApplication::NSApplicationBlockTermination is telling
- * you that OSX is planning to shut down your program. If you have any
+ * you that OS X is planning to shut down your program. If you have any
  * cleanup to do (like saving open files), or if you want to ask the
  * user if it's OK, you should connect to the signal and do your
  * cleanup. Your handler can return %TRUE to prevent the application
@@ -262,7 +274,7 @@ gtkosx_application_use_quartz_accelerators (GtkosxApplication *self)
  * @use_quartz_accelerators: Gboolean
  *
  * Set quartz accelerator handling; TRUE (default) uses quartz; FALSE
- * uses Gtk+. Quartz accelerator handling is required for normal OSX
+ * uses Gtk+. Quartz accelerator handling is required for normal OS X
  * accelerators (e.g., command-q to quit) to work.
  */
 void
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]