Merge pull request #65 from chimara/glk-0.7.5

Implement version 0.7.5 of Glk spec
chimara · Jan 2, 2024 · 92235eb · 92235eb
2 parents 04ff30a + cb925e9
commit 92235eb
Show file tree

Hide file tree

Showing 37 changed files with 1,788 additions and 172 deletions.
diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
@@ -19,7 +19,7 @@
   </reference>
 
   <reference id="chimara-glk-api-spec">
-    <title>Glk API Specification, version 0.7.4</title>
+    <title>Glk API Specification, version 0.7.5</title>
     <xi:include href="glk-front-matter.sgml"/>
 
     <!-- Chapter 0. Introduction -->
@@ -143,6 +143,7 @@
       <xi:include href="xml/dispatch-interrogating.xml"/>
       <xi:include href="xml/dispatch-dispatching.xml"/>
       <xi:include href="xml/dispatch-prototypes.xml"/>
+      <xi:include href="xml/dispatch-game-id.xml"/>
       <xi:include href="xml/dispatch-library-functions.xml"/>
       <xi:include href="dispatch-selectors.sgml"/>
     </appendix>

diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt
@@ -75,6 +75,7 @@ CHIMARA_IF_GET_CLASS
 glk_exit
 <SUBSECTION Private>
 glk_main
+GLK_ATTRIBUTE_NORETURN
 </SECTION>
 
 <SECTION>
@@ -139,6 +140,7 @@ gestalt_Hyperlinks
 gestalt_HyperlinkInput
 gestalt_SoundMusic
 gestalt_GraphicsTransparency
+gestalt_GraphicsCharInput
 gestalt_DateTime
 gestalt_ResourceStream
 GLK_MODULE_RESOURCE_STREAM
@@ -615,13 +617,23 @@ gluniversal_t
 gidispatch_prototype
 </SECTION>
 
+<SECTION>
+<FILE>dispatch-game-id</FILE>
+<TITLE>Querying a game ID string</TITLE>
+GI_DISPA_GAME_ID_AVAILABLE
+gidispatch_set_game_id_hook
+gidispatch_get_game_id
+</SECTION>
+
 <SECTION>
 <FILE>dispatch-library-functions</FILE>
 <TITLE>Functions the Library Must Provide</TITLE>
 gidispatch_set_object_registry
 gidispatch_rock_t
 gidispatch_get_objrock
 gidispatch_set_retained_registry
+GIDISPATCH_AUTORESTORE_REGISTRY
+gidispatch_set_autorestore_registry
 </SECTION>
 
 <INCLUDE>libchimara/glk.h, libchimara/gi-blorb.h</INCLUDE>
@@ -645,6 +657,8 @@ giblorb_load_chunk_by_number
 giblorb_unload_chunk
 giblorb_load_resource
 giblorb_count_resources
+giblorb_image_info_t
+giblorb_load_image_info
 <SUBSECTION Constants>
 giblorb_method_DontLoad
 giblorb_method_Memory
@@ -658,6 +672,8 @@ giblorb_ID_AUTH
 giblorb_ID_ANNO
 giblorb_ID_TEXT
 giblorb_ID_BINA
+giblorb_ID_JPEG
+giblorb_ID_PNG
 <SUBSECTION Private>
 giblorb_make_id
 </SECTION>

diff --git a/docs/reference/dispatch-selectors.sgml b/docs/reference/dispatch-selectors.sgml
@@ -31,8 +31,10 @@ An earlier version of Glk had gestalt selectors <code>gestalt_FunctionNameToID</
 They are defined and used only by the dispatch layer.
 </para>
 <para>
-Call selectors 0x1200 to 0x12FF are reserved for extension projects by Carlos Sanchez.
-The same is true of gestalt selector 0x1200.
+Call selectors 0x1100 to 0x11FF (and the same range of gestalt selectors) are reserved for extension projects by Dannii Willis.
+Call selectors 0x1200 to 0x12FF (and gestalt selector 0x1200) are reserved for extension projects by Carlos Sanchez.
+Call selectors 0x2200 to 0x22FF (and the same range of gestalt selectors) are reserved for iOS extension features by Andrew Plotkin.
+Call selectors 0x1400 to 0x14FF (and the same range of gestalt selectors) are reserved for extension projects by ZZO38.
 These are not documented here.
 </para>
 </refsect1>

diff --git a/docs/reference/glk-front-matter.sgml b/docs/reference/glk-front-matter.sgml
@@ -3,18 +3,15 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
 <referenceinfo>
-<title>Glk API Specification</title>
-<subtitle>API version 0.7.4</subtitle>
-<author>
-  <personname>
-    <firstname>Andrew</firstname>
-    <surname>Plotkin</surname>
-  </personname>
-  <email>[email protected]</email>
-</author>
+<title>Glk: A Portable Interface Standard for IF</title>
+<subtitle>API specification version 0.7.5</subtitle>
+<publisher>
+  <publishername>Maintained by IFTF</publishername>
+  <email>[email protected]</email>
+</publisher>
 <copyright>
-  <year>1998&ndash;2012</year>
-  <holder>Andrew Plotkin</holder>
+  <year>2020</year>
+  <holder>the <ulink href="https://iftechfoundation.org/">Interactive Fiction Technology Foundation</ulink></holder>
 </copyright>
 <legalnotice>
 <para>
@@ -26,6 +23,6 @@ Anyone is free to write programs that use the Glk API or libraries that implemen
 </para>
 </legalnotice>
 <releaseinfo>
-The authors of the Chimara library have adapted this document to better fit the format of a GtkDoc reference manual. They have also added notes specific to Chimara's implementation of the Glk API. The original API specification and further Glk information can be found at: <ulink url="http://eblong.com/zarf/glk/"/>
+The authors of the Chimara library have adapted this document to better fit the format of a GtkDoc reference manual. They have also added notes specific to Chimara's implementation of the Glk API. The original API specification and further Glk information can be found at: <ulink url="https://github.com/iftechfoundation/ifarchive-if-specs"/>
 </releaseinfo>
 </referenceinfo>
diff --git a/docs/reference/glk-window-arrangement.sgml b/docs/reference/glk-window-arrangement.sgml
@@ -131,5 +131,16 @@ So the root window is the ancestor of every other window.
 <para>
 There are Glk functions to determine the root window, and to determine the parent of any given window. Note that every window's parent is a pair window. (Except for the root window, which has no parent.)
 </para>
+<para>
+A note about zero-size windows: a window may wind up with a height or width of zero.
+(Because of a fixed height of zero, or a percentage allocation of zero, or simply because the application display area does not have enough space.)
+The library should support this by hiding the window and its contents entirely.
+Any border between the window and its sibling should also disappear.
+</para>
+<note><para>
+When a window has zero size, it is reasonable for the library to stop passing input events to it.
+The input request is not cancelled, but the UI may not be able to give keyboard focus or mouse events to a zero-size region of the screen.
+Therefore, a program which sets a window to zero size should not rely on input from it.
+</para></note>
 </refsect1>
 </refentry>
diff --git a/docs/reference/glk-windows.sgml b/docs/reference/glk-windows.sgml
@@ -52,7 +52,9 @@ A window has a type. Currently there are four window types:
 <varlistentry>
 	<term>Graphics windows</term>
 	<listitem><para>
-	A grid of colored pixels. Graphics windows do not support text input or output, but there are image commands to draw in them.
+	A grid of colored pixels.
+    Graphics windows do not support text output, but there are image commands to draw in them.
+    Graphics windows can accept character (keystroke) input, but not line input.
 	</para>
 	<note><para>This is an optional capability; not all Glk libraries support graphics. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics Capabilities</link>.
 	</para></note></listitem>

diff --git a/docs/reference/meson.build b/docs/reference/meson.build
@@ -52,6 +52,7 @@ gnome.gtkdoc('chimara',
         'ui-message.h',
         'window.h',
     ],
+    scan_args: ['--ignore-decorators=GLK_ATTRIBUTE_NORETURN'],
     mkdb_args: [
         '--sgml-mode',
         '--output-format=xml',

diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c
@@ -597,6 +597,11 @@ chimara_glk_get_preferred_height(GtkWidget *widget, int *minimal, int *natural)
 static winid_t
 allocate_recurse(winid_t win, GtkAllocation *allocation, guint spacing)
 {
+	if (allocation->width == 0 || allocation->height == 0) {
+		/* Just don't show this window */
+		return win;
+	}
+
 	if(win->type == wintype_Pair)
 	{
 		g_mutex_lock(&win->lock);
@@ -693,7 +698,18 @@ allocate_recurse(winid_t win, GtkAllocation *allocation, guint spacing)
 				child1.width = child2.width = allocation->width;
 				break;
 		}
-
+
+		/* If either of the child windows get 0 size, hide that window and just
+		 * give the full space to the other one */
+		if (child1.width == 0 || child1.height == 0) {
+			allocate_recurse(win->window_node->children->next->data, allocation, spacing);
+			return win;
+		}
+		if (child2.width == 0 || child2.height == 0) {
+			allocate_recurse(win->window_node->children->data, allocation, spacing);
+			return win;
+		}
+
 		/* Recurse */
 		winid_t arrange1 = allocate_recurse(win->window_node->children->data, &child1, spacing);
 		winid_t arrange2 = allocate_recurse(win->window_node->children->next->data, &child2, spacing);

diff --git a/libchimara/dispatch.c b/libchimara/dispatch.c
@@ -199,3 +199,25 @@ gidispatch_set_retained_registry(gidispatch_rock_t (*regi)(void *array, glui32 l
 	glk_data->register_arr = regi;
 	glk_data->unregister_arr = unregi;
 }
+
+/**
+ * gidispatch_set_autorestore_registry:
+ * @locatearr:
+ * @restorearr:
+ *
+ * This function is also part of the Glk library, but it only exists on
+ * libraries that support autorestore.
+ * (Only iosglk, currently.)
+ * Only call this if %GIDISPATCH_AUTORESTORE_REGISTRY is defined.
+ *
+ * > # Chimara #
+ * > This function does nothing in Chimara.
+ *
+ * Stability: Unstable
+ */
+void
+gidispatch_set_autorestore_registry(
+    long (*locatearr)(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock, int *elemsizeref),
+    gidispatch_rock_t (*restorearr)(long bufkey, glui32 len, char *typecode, void **arrayref))
+{
+}