bug#51716: 29.0.50; [PATCH] Expose xwidget navigation history to Lisp code

[Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 5174 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> This should be @var, not @code.

>> +in its navigation history.
>> +
>> +If @var{rel-pos} is zero, the current page will be reloaded instead.
>> +@end defun
>> +
>> +@defun xwidget-webkit-back-forward-list xwidget &optional limit
>
> Hmm... given that we have xwidget-webkit-goto-history, why do we need
> this new function as well?  Or why do we need both?

`xwidget-webkit-goto-history' only lets you navigate to a history index:
it doesn't tell you what that index actually is, or indeed, if it even
exists at all.

>> +The returned value is a list of the form @code{(@var{back} @var{here}
>> +@var{forward})}

> This list should be wrapped in @w{..}, so that it is kept unbroken
> between 2 lines.

Thanks.

>> where @var{here} is the current navigation item,
>> +while @var{back} is a list of items containing the history behind the
>> +current navigation item, and @var{forward} is a list of items in front
>> +of the current navigation item.
>
> The notions of "behind" and "in front" are not well-defined in this
> context.  The text should make more clear what does each one of those
> mean.

I tried to clarify, thanks.

>>                                  @var{back}, @var{here} and
>> +@var{forward} can all be @code{nil}.

> What is the meaning of each one being nil?  The text leaves that
> unsaid.

BACK being nil means that we are at the beginning of the history.
FORWARD being nil means that there is nothing after the current place in
history.  HERE being nil means that WebKit hasn't recorded any pages in
history yet.

I will add that to the documentation, thanks.

> Please use @w{..} here as well.  basically you should use it for any
> form that has embedded whitespace, and can therefore be split between
> two lines when Texinfo fills and justifies the text.

Done, thanks.

>>                           In these lists, @var{idx} is an index that
>> +can be passed to @code{xwidget-webkit-goto-history}, @var{title} is
>> +the human-readable title of the item, and @var{uri} is the URI of the
>> +item.

> URI, not URL?

Yes, as WebKit allows any URI to appear in history items.

>> +DEFUN ("xwidget-webkit-back-forward-list", Fxwidget_webkit_back_forward_list,
>> +       Sxwidget_webkit_back_forward_list, 1, 2, 0,
>> +       doc: /* Return the navigation history of XWIDGET, a WebKit xwidget.
>> +
>> +The history is returned as a list of the form (BACK HERE FORWARD),
>    ^^^^^^^^^^^^^^^^^^^^^^^
> Passive tense alert!

[...]

> "lists of ... , which are lists" uses "lists" twice, which is
> redundant.  Better say
>
>    ... are lists of elements of the form (IDX TITLE URI) ...

Thanks, I fixed.

> This belongs to the manual, not a doc string.

Thanks, I moved it there.

> Each one or both together? the text is ambiguous about that.

I tried to fix that, please check.  Thanks.

>> +#ifdef USE_GTK
>> +  webview = WEBKIT_WEB_VIEW (xw->widget_osr);
>
> I guess this again means this function is a no-op without GTK?  Then
> let's not define it except in the GTK build.

Done, thanks.

>> +  list = webkit_web_view_get_back_forward_list (webview);
>> +  item = webkit_back_forward_list_get_current_item (list);
>> +  lim = XFIXNAT (limit);
>> +
>> +  if (item)
>> +    {
>> +      item_title = webkit_back_forward_list_item_get_title (item);
>> +      item_uri = webkit_back_forward_list_item_get_uri (item);
>> +      here = list3 (make_fixnum (0),
>> +		    build_string (item_title ? item_title : ""),
>> +		    build_string (item_uri ? item_uri : ""));
>> +    }
>> +  parent = webkit_back_forward_list_get_back_list_with_limit (list, lim);
>> +
>> +  if (parent)
>> +    {
>> +      for (i = 1, tem = parent; parent; parent = parent->next, ++i)
>> +	{
>> +	  item = tem->data;
>> +	  item_title = webkit_back_forward_list_item_get_title (item);
>> +	  item_uri = webkit_back_forward_list_item_get_uri (item);
>> +	  title = build_string (item_title ? item_title : "");
>> +	  uri = build_string (item_uri ? item_uri : "");

> build_string can produce either multibyte or unibyte strings.  Which
> ones do we want?  And shouldn't we decode the strings that come from
> WebKit?

Sorry for that. We want UTF-8 strings, as that's the format of strings
which come from WebKitGTK.  (And most GLib-related software, as well).

>> +	  back = Fcons (list3 (make_fixnum (-i), title, uri), back);
>> +	}
>> +    }
>> +
>> +  g_list_free (parent);
>> +
>> +  parent = webkit_back_forward_list_get_forward_list_with_limit (list, lim);
>> +
>> +  if (parent)
>> +    {
>> +      for (i = 1, tem = parent; parent; parent = parent->next, ++i)
>> +	{
>> +	  item = tem->data;
>> +	  item_title = webkit_back_forward_list_item_get_title (item);
>> +	  item_uri = webkit_back_forward_list_item_get_uri (item);
>> +	  title = build_string (item_title ? item_title : "");
>> +	  uri = build_string (item_uri ? item_uri : "");
>> +	  forward = Fcons (list3 (make_fixnum (i), title, uri), forward);
>> +	}

> This generates the lists in the reverse order, doesn't it?

Yes, but what's important here is the index `i', not the order of the
list.  But I agree that it would be OK to nreverse the contents of that
list.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Expose-xwidget-navigation-history-to-Lisp-code.patch --]
[-- Type: text/x-patch, Size: 6794 bytes --]

From 920ae609bb5fbeab4bb9511fd5539978c10c4448 Mon Sep 17 00:00:00 2001
From: Po Lu <luangruo@yahoo.com>
Date: Thu, 11 Nov 2021 09:01:38 +0800
Subject: [PATCH] Expose xwidget navigation history to Lisp code

* doc/lispref/display.texi (Xwidgets): Document changes.
* etc/NEWS: Announce new function.
* src/xwidget.c (Fxwidget_webkit_back_forward_list): New function.
(syms_of_xwidget): Define new subr.
---
 doc/lispref/display.texi | 33 ++++++++++++++
 etc/NEWS                 |  5 +++
 src/xwidget.c            | 95 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 133 insertions(+)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ad1077e0c4..094bb5a5f3 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6953,6 +6953,39 @@ Xwidgets
 to be used for resolving relative links in @var{text}.
 @end defun
 
+@defun xwidget-webkit-goto-history xwidget rel-pos
+Make @var{xwidget}, a WebKit widget, load the @var{rel-pos}th element
+in its navigation history.
+
+If @var{rel-pos} is zero, the current page will be reloaded instead.
+@end defun
+
+@defun xwidget-webkit-back-forward-list xwidget &optional limit
+Return the navigation history of @var{xwidget}, up to @var{limit}
+items in each direction.  If not specified, @var{limit} defaults to
+50.
+
+The returned value is a list of the form @w{@code{(@var{back}
+@var{here} @var{forward})}}, where @var{here} is the current
+navigation item, while @var{back} is a list of items containing the
+items recorded by WebKit before the current navigation item, and
+@var{forward} is a list of items recorded after the current navigation
+item.  @var{back}, @var{here} and @var{forward} can all be @code{nil}.
+
+When @var{here} is @code{nil}, it means that no items have been
+recorded yet; if @var{back} or @var{forward} are @code{nil}, it means
+that there is no history recorded before or after the current item
+respectively.
+
+Navigation items are themselves lists of the form @w{@code{(@var{idx}
+@var{title} @var{uri})}}.  In these lists, @var{idx} is an index that
+can be passed to @code{xwidget-webkit-goto-history}, @var{title} is
+the human-readable title of the item, and @var{uri} is the URI of the
+item.  The user should normally have no reason to load @var{uri}
+manually to reach a specific history item.  Instead, @var{idx} should
+be passed as an index to @code{xwidget-webkit-goto-history}.
+@end defun
+
 @node Buttons
 @section Buttons
 @cindex buttons in buffers
diff --git a/etc/NEWS b/etc/NEWS
index 78ce3c067f..7702cec92c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -747,6 +747,11 @@ markup, and passing the URI of the file as an argument to
 Some new functions, such as 'xwidget-webkit-search', have been added
 for performing searches on WebKit xwidgets.
 
++++
+*** New function 'xwidget-webkit-back-forward-list'.
+This function is used to obtain the history of page-loads in a given
+WebKit xwidget.
+
 +++
 *** 'load-changed' xwidget events are now more detailed.
 In particular, they can now have different arguments based on the
diff --git a/src/xwidget.c b/src/xwidget.c
index fc05f4f570..ace63e3742 100644
--- a/src/xwidget.c
+++ b/src/xwidget.c
@@ -20,6 +20,7 @@ Copyright (C) 2011-2021 Free Software Foundation, Inc.
 #include <config.h>
 
 #include "buffer.h"
+#include "coding.h"
 #include "xwidget.h"
 
 #include "lisp.h"
@@ -2314,6 +2315,99 @@ DEFUN ("xwidget-webkit-load-html", Fxwidget_webkit_load_html,
 
   return Qnil;
 }
+
+DEFUN ("xwidget-webkit-back-forward-list", Fxwidget_webkit_back_forward_list,
+       Sxwidget_webkit_back_forward_list, 1, 2, 0,
+       doc: /* Return the navigation history of XWIDGET, a WebKit xwidget.
+
+Return the history as a list of the form (BACK HERE FORWARD), where
+HERE is the current navigation item, while BACK and FORWARD are lists
+of history items of the form (IDX TITLE URI).  Here, IDX is an index
+that can be passed to `xwidget-webkit-goto-history', TITLE is a string
+containing the human-readable title of the history item, and URI is
+the URI of the history item.
+
+BACK, HERE, and FORWARD can all be nil depending on the state of the
+navigation history.
+
+BACK and FORWARD will each not contain more elements than LIMIT.  If
+LIMIT is not specified or nil, it is treated as `50'.  */)
+  (Lisp_Object xwidget, Lisp_Object limit)
+{
+  struct xwidget *xw;
+  Lisp_Object back, here, forward;
+  WebKitWebView *webview;
+  WebKitBackForwardList *list;
+  WebKitBackForwardListItem *item;
+  GList *parent, *tem;
+  int i;
+  unsigned int lim;
+  Lisp_Object title, uri;
+  const gchar *item_title, *item_uri;
+
+  back = Qnil;
+  here = Qnil;
+  forward = Qnil;
+
+  if (NILP (limit))
+    limit = make_fixnum (50);
+  else
+    CHECK_FIXNAT (limit);
+
+  CHECK_XWIDGET (xwidget);
+  xw = XXWIDGET (xwidget);
+
+  webview = WEBKIT_WEB_VIEW (xw->widget_osr);
+  list = webkit_web_view_get_back_forward_list (webview);
+  item = webkit_back_forward_list_get_current_item (list);
+  lim = XFIXNAT (limit);
+
+  if (item)
+    {
+      item_title = webkit_back_forward_list_item_get_title (item);
+      item_uri = webkit_back_forward_list_item_get_uri (item);
+      here = list3 (make_fixnum (0),
+		    build_string_from_utf8 (item_title ? item_title : ""),
+		    build_string_from_utf8 (item_uri ? item_uri : ""));
+    }
+  parent = webkit_back_forward_list_get_back_list_with_limit (list, lim);
+
+  if (parent)
+    {
+      for (i = 1, tem = parent; parent; parent = parent->next, ++i)
+	{
+	  item = tem->data;
+	  item_title = webkit_back_forward_list_item_get_title (item);
+	  item_uri = webkit_back_forward_list_item_get_uri (item);
+	  title = build_string_from_utf8 (item_title ? item_title : "");
+	  uri = build_string_from_utf8 (item_uri ? item_uri : "");
+	  back = Fcons (list3 (make_fixnum (-i), title, uri), back);
+	}
+    }
+
+  back = Fnreverse (back);
+  g_list_free (parent);
+
+  parent = webkit_back_forward_list_get_forward_list_with_limit (list, lim);
+
+  if (parent)
+    {
+      for (i = 1, tem = parent; parent; parent = parent->next, ++i)
+	{
+	  item = tem->data;
+	  item_title = webkit_back_forward_list_item_get_title (item);
+	  item_uri = webkit_back_forward_list_item_get_uri (item);
+	  title = build_string_from_utf8 (item_title ? item_title : "");
+	  uri = build_string_from_utf8 (item_uri ? item_uri : "");
+	  forward = Fcons (list3 (make_fixnum (i), title, uri), forward);
+	}
+    }
+
+  forward = Fnreverse (forward);
+  g_list_free (parent);
+
+  return list3 (back, here, forward);
+}
 #endif
 
 void
@@ -2356,6 +2450,7 @@ syms_of_xwidget (void)
   defsubr (&Sset_xwidget_buffer);
 #ifdef USE_GTK
   defsubr (&Sxwidget_webkit_load_html);
+  defsubr (&Sxwidget_webkit_back_forward_list);
 #endif
 
   DEFSYM (QCxwidget, ":xwidget");
-- 
2.31.1