From: Eli Zaretskii Date: Sun, 7 Nov 2021 09:50:06 +0000 (+0200) Subject: Fix documentation and coding style in recent xwidget commits X-Git-Tag: emacs-29.0.90~3671^2~113 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d5bb053809bfe2f2605ada15a7ccd25d772b0102;p=emacs.git Fix documentation and coding style in recent xwidget commits * src/xwidget.c (Fmake_xwidget, find_widget) (xwidget_motion_or_crossing, xwidget_button_1, xwidget_button): Fix style in comments. (Fxwidget_perform_lispy_event): Doc fix. * src/xwidget.c (set_widget_if_text_view, kill_frame_xwidget_views): * src/keyboard.c (make_lispy_event): Fix style of braces. * lisp/xwidget.el (xwidget-webkit-isearch-mode): Fix keys in doc string. * doc/lispref/commands.texi (Xwidget Events): Fix markup and wording. * doc/lispref/display.texi (Xwidgets): Fix wording and markup. * doc/emacs/misc.texi (Embedded WebKit Widgets): Fix wording. * etc/NEWS: Fix wording and punctuation. --- diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 1207ab5e9a0..4b3c2ea4bd2 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -2965,19 +2965,18 @@ You can also enable @code{xwidget-webkit-edit-mode} by typing @kbd{e} inside the xwidget webkit buffer. @findex xwidget-webkit-isearch-mode -@cindex xwidget-webkit-isearch-mode @cindex searching in webkit buffers @code{xwidget-webkit-isearch-mode} is a minor mode that behaves similarly to incremental search (@pxref{Incremental Search}), but operates on the contents of a WebKit widget instead of the current buffer. It is bound to @kbd{C-s} and @kbd{C-r} inside xwidget-webkit -buffers. When it is enabled through @kbd{C-r}, the initial search -will be performed in reverse direction. +buffers. When it is invoked by @kbd{C-r}, the initial search will be +performed in reverse direction. Typing any self-inserting character will cause the character to be inserted into the current search query. Typing @kbd{C-s} will cause the WebKit widget to display the next search result, while typing -@kbd{C-r} will cause it to display the last. +@kbd{C-r} will cause it to display the previous one. To leave incremental search, you can type @kbd{C-g}. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 832b570b6a4..6ed46fa6a27 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1883,53 +1883,62 @@ contain various data describing the nature of the change. @cindex @code{xwidget-event} event @item (xwidget-event @var{kind} @var{xwidget} @var{arg}) This event is sent whenever some kind of update occurs in -@var{xwidget}. There are several types of updates, which are -identified by @var{kind}. - -@cindex @code{load-changed} xwidget events -An xwidget event with @var{kind} set to @code{load-changed} indicates -that the @var{xwidget} has reached a particular point of the -page-loading process. When these events are sent, @var{arg} will -contain a string that futher describes the status of the widget. - -@cindex @samp{"load-finished"} in xwidgets -When @var{arg} is @samp{"load-finished"}, it means the xwidget has -finished processing whatever page-loading operation that it was -previously performing. - -@cindex @samp{"load-started"} in xwidgets -Otherwise, if it is @samp{"load-started"}, then the widget has begun a -page-loading operation. - -@cindex @samp{"load-redirected"} in xwidgets -If @var{arg} is @samp{"load-redirected"}, it means the widget has -encountered and followed a redirect during the page-loading operation. - -@cindex @samp{"load-committed"} in xwidgets -If @var{arg} is @samp{"load-committed"}, then the widget has committed -to a given URL during the page-loading operation. This means that the -URL is the final URL that will be rendered by @var{xwidget} during the -current page-loading operation. +@var{xwidget}. There are several types of updates, identified by +their @var{kind}. + +@table @code +@cindex @code{load-changed} xwidget event +@item load-changed +This xwidget event indicates that the @var{xwidget} has reached a +particular point of the page-loading process. When these events are +sent, @var{arg} will contain a string that futher describes the status +of the widget: + +@table @samp +@cindex @samp{load-started} in xwidgets +@item load-started +This means the widget has begun a page-loading operation. + +@cindex @samp{load-finished} in xwidgets +@item load-finished +This means the @var{xwidget} has finished processing whatever +page-loading operation that it was previously performing. + +@cindex @samp{load-redirected} in xwidgets +@item load-redirected +This means the @var{xwidget} has encountered and followed a redirect +during the page-loading operation. + +@cindex @samp{load-committed} in xwidgets +@item load-committed +This means the @var{xwidget} has committed to a given URL during the +page-loading operation, i.e.@: the URL is the final URL that will be +rendered by @var{xwidget} during the current page-loading operation. +@end table @cindex @code{download-callback} xwidget events -An event with @var{kind} set to @code{download-callback} indicates -that a download of some kind has been completed. +@item download-callback +This event indicates that a download of some kind has been completed. +@end table -In these events, there can be arguments after @var{arg}, which itself -indicates the URL that the download file was retrieved from: the first -argument after @var{arg} indicates the MIME type of the download, as a -string, while the second such argument contains the full file path to -the downloaded file. +In the above events, there can be arguments after @var{arg}, which +itself indicates the URL from which the download file was retrieved: +the first argument after @var{arg} indicates the MIME type of the +download, as a string, while the second argument contains the full +file name of the downloaded file. +@table @code @cindex @code{download-started} xwidget events -An event with @var{kind} set to @code{download-started} indicates that -a download has been started. In these events, @var{arg} contains the -URL of the file that is currently being downloaded. +@item download-started +This event indicates that a download has been started. In these +events, @var{arg} contains the URL of the file that is currently being +downloaded. @cindex @code{javascript-callback} xwidget events -An event with @var{kind} set to @code{javascript-callback} contains -JavaScript callback data. These events are used internally by -@code{xwidget-webkit-execute-script}. +@item javascript-callback +This event contains JavaScript callback data. These events are used +internally by @code{xwidget-webkit-execute-script}. +@end table @cindex @code{xwidget-display-event} event @item (xwidget-display-event @var{xwidget}) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 60bca15eb21..b6bd14f8874 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -6890,22 +6890,22 @@ query-on-exit flag, either @code{t} or @code{nil}. @defun xwidget-perform-lispy-event xwidget event frame Send an input event @var{event} to @var{xwidget}. The precise action -performed is platform-specific. See @ref{Input Events}. +performed is platform-specific. @xref{Input Events}. -You can optionally pass the frame the event was generated from via +You can optionally pass the frame on which the event was generated via @var{frame}. On X11, modifier keys in key events will not be considered if @var{frame} is @code{nil}, and the selected frame is not an X-Windows frame. -On GTK, only keyboard and function key events are implemented. Mouse, +On GTK, only keyboard and function key events are supported. Mouse, motion, and click events are dispatched to the xwidget without going through Lisp code, and as such shouldn't require this function to be -sent. +called. @end defun @defun xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around Start an incremental search on the WebKit widget @var{xwidget} with -the string @var{query} as a query. @var{case-insensitive} denotes +the string @var{query} as the query. @var{case-insensitive} denotes whether or not the search is case-insensitive, @var{backwards} determines if the search is performed backwards towards the start of the document, and @var{wrap-around} determines whether or not the @@ -6919,28 +6919,28 @@ To stop a search query, use @code{xwidget-webkit-finish-search}. @defun xwidget-webkit-next-result xwidget Display the next search result in @var{xwidget}. This function will -error unless a search query has already been started in @var{xwidget} -through @code{xwidget-webkit-search}. +signal an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} was called, then the search will restart from the beginning of the -document if the end is reached. +document when its end is reached. @end defun @defun xwidget-webkit-previous-result xwidget Display the previous search result in @var{xwidget}. This function -will error unless a search query has already been started in +signals an error if a search query has not been already started in @var{xwidget} through @code{xwidget-webkit-search}. If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} was called, then the search will restart from the end of the -document if the beginning is reached. +document when its beginning is reached. @end defun @defun xwidget-webkit-finish-search xwidget Finish a search operation started with @code{xwidget-webkit-search} in -@var{xwidget}. If there is no query currently ongoing, then this -function will error. +@var{xwidget}. If there is no query currently ongoing, this function +signals an error. @end defun @node Buttons diff --git a/etc/NEWS b/etc/NEWS index b14f9a2549a..4c1513a73e7 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -498,16 +498,16 @@ This is a convenience function to extract the field data from ** Xwidgets +++ -*** New minor mode `xwidget-webkit-edit-mode'. +*** New minor mode 'xwidget-webkit-edit-mode'. When this mode is enabled, self-inserting characters and other common web browser shotcut keys are redefined to send themselves to the WebKit widget. +++ -*** New minor mode `xwidget-webkit-isearch-mode'. +*** New minor mode 'xwidget-webkit-isearch-mode'. This mode acts similarly to incremental search, and allows to search the contents of a WebKit widget. In xwidget-webkit mode, it is bound -to `C-s' and `C-r'. +to 'C-s' and 'C-r'. --- *** On X11, the WebKit inspector is now available inside xwidgets. @@ -516,8 +516,8 @@ Element". --- *** "Open in New Window" in a WebKit widget's context menu now works. -The newly created buffer will be displayed via display-buffer, which -can be customized through the usual mechanism of display-buffer-alist +The newly created buffer will be displayed via 'display-buffer', which +can be customized through the usual mechanism of 'display-buffer-alist' and friends. @@ -745,13 +745,15 @@ an exact match, then the lowercased '[menu-bar foo\ bar]' and finally when converting menus to use 'easy-menu-define'. +++ -** The function `make-xwidget' now accepts an optional RELATED argument. +** xwidgets + +*** The function 'make-xwidget' now accepts an optional RELATED argument. This argument is used as another widget for the newly created WebKit widget to share settings and subprocesses with. It must be another WebKit widget. +++ -** New function `xwidget-perform-lispy-event'. +*** New function 'xwidget-perform-lispy-event'. This function allows you to send events to xwidgets. Usually, some equivalent of the event will be sent, but there is no guarantee of what the widget will actually receive. @@ -759,23 +761,23 @@ what the widget will actually receive. On GTK+, only key and function key events are implemented. +++ -** New functions for performing searches on WebKit xwidgets. -Some new functions, such as `xwidget-webkit-search', have been added +*** New functions for performing searches on WebKit xwidgets. +Some new functions, such as 'xwidget-webkit-search', have been added for performing searches on WebKit xwidgets. +++ -** `load-changed' xwidget events are now more detailed. +*** 'load-changed' xwidget events are now more detailed. In particular, they can now have different arguments based on the -state of the WebKit widget. `load-finished' is sent when a load has -completed, `load-started' when a load first starts, `load-redirected' -after a redirect, and `load-committed' when the WebKit widget first +state of the WebKit widget. 'load-finished' is sent when a load has +completed, 'load-started' when a load first starts, 'load-redirected' +after a redirect, and 'load-committed' when the WebKit widget first commits to the load. +++ -** New event type `xwidget-display-event'. +*** New event type 'xwidget-display-event'. These events are sent whenever an xwidget requests that Emacs display -another. The only argument to this event is the xwidget that should -be displayed. +another xwidget. The only argument to this event is the xwidget that +should be displayed. * Changes in Emacs 29.1 on Non-Free Operating Systems diff --git a/lisp/xwidget.el b/lisp/xwidget.el index 1e169d56509..4bd2be2c264 100644 --- a/lisp/xwidget.el +++ b/lisp/xwidget.el @@ -926,18 +926,17 @@ With argument, add COUNT copies of CHAR." (define-minor-mode xwidget-webkit-isearch-mode "Minor mode for performing incremental search inside WebKit buffers. -An attempt was made for this to resemble regular incremental -search, but it suffers from several limitations, such as not -supporting recursive edits. +This resembles the regular incremental search, but it does not +support recursive edits. -If this mode is enabled with `C-r', then the search will default -to being performed in reverse direction. +If this mode is activated with `\\\\[xwidget-webkit-isearch-backward]', then the search will by default +start in the reverse direction. To navigate around the search results, type -\\[xwidget-webkit-isearch-forward] to move forward, and -\\[xwidget-webkit-isearch-backward] to move backward. +\\\\[xwidget-webkit-isearch-forward] to move forward, and +\\\\[xwidget-webkit-isearch-backward] to move backward. -Press \\[xwidget-webkit-isearch-exit] to exit incremental search." +Press \\\\[xwidget-webkit-isearch-exit] to exit incremental search." :keymap xwidget-webkit-isearch-mode-map (if xwidget-webkit-isearch-mode (progn diff --git a/src/keyboard.c b/src/keyboard.c index c4a5671b104..de9805df327 100644 --- a/src/keyboard.c +++ b/src/keyboard.c @@ -6123,28 +6123,20 @@ make_lispy_event (struct input_event *event) #ifdef HAVE_DBUS case DBUS_EVENT: - { - return Fcons (Qdbus_event, event->arg); - } + return Fcons (Qdbus_event, event->arg); #endif /* HAVE_DBUS */ #ifdef THREADS_ENABLED case THREAD_EVENT: - { - return Fcons (Qthread_event, event->arg); - } + return Fcons (Qthread_event, event->arg); #endif /* THREADS_ENABLED */ #ifdef HAVE_XWIDGETS case XWIDGET_EVENT: - { - return Fcons (Qxwidget_event, event->arg); - } + return Fcons (Qxwidget_event, event->arg); case XWIDGET_DISPLAY_EVENT: - { - return list2 (Qxwidget_display_event, event->arg); - } + return list2 (Qxwidget_display_event, event->arg); #endif #ifdef USE_FILE_NOTIFY diff --git a/src/xwidget.c b/src/xwidget.c index 78a3860490f..66d84ee25a5 100644 --- a/src/xwidget.c +++ b/src/xwidget.c @@ -174,8 +174,7 @@ fails. */) /* webkitgtk uses GSubprocess which sets sigaction causing Emacs to not catch SIGCHLD with its usual handle setup in - catch_child_signal(). This resets the SIGCHLD - sigaction. */ + 'catch_child_signal'. This resets the SIGCHLD sigaction. */ struct sigaction old_action; sigaction (SIGCHLD, NULL, &old_action); webkit_web_view_load_uri (WEBKIT_WEB_VIEW (xw->widget_osr), @@ -188,7 +187,7 @@ fails. */) xw->widget_osr = webkit_web_view_new_with_related_view (related_view); } - /* Enable the developer extras */ + /* Enable the developer extras. */ settings = webkit_web_view_get_settings (WEBKIT_WEB_VIEW (xw->widget_osr)); g_object_set (G_OBJECT (settings), "enable-developer-extras", TRUE, NULL); } @@ -262,9 +261,7 @@ set_widget_if_text_view (GtkWidget *widget, void *data) GtkWidget **pointer = data; if (GTK_IS_TEXT_VIEW (widget)) - { - *pointer = widget; - } + *pointer = widget; } #endif @@ -272,9 +269,9 @@ DEFUN ("xwidget-perform-lispy-event", Fxwidget_perform_lispy_event, Sxwidget_perform_lispy_event, 2, 3, 0, doc: /* Send a lispy event to XWIDGET. EVENT should be the event that will be sent. FRAME should be the -frame which generated the event, or nil. On X11, modifier keys will -not be processed if FRAME is nil and the selected frame is not an -X-Windows frame. */) +frame which generated the event, and defaults to the selected frame. +On X11, modifier keys will not be processed if FRAME is nil and the +selected frame is not an X-Windows frame. */) (Lisp_Object xwidget, Lisp_Object event, Lisp_Object frame) { struct xwidget *xw; @@ -503,39 +500,39 @@ find_widget (GtkWidget *widget, { window = gtk_widget_get_window (widget); while (window != gtk_widget_get_window (gtk_widget_get_parent (widget))) - { - gint tx, ty, twidth, theight; + { + gint tx, ty, twidth, theight; if (!window) return; - twidth = gdk_window_get_width (window); - theight = gdk_window_get_height (window); + twidth = gdk_window_get_width (window); + theight = gdk_window_get_height (window); - if (new_allocation.x < 0) - { - new_allocation.width += new_allocation.x; - new_allocation.x = 0; - } + if (new_allocation.x < 0) + { + new_allocation.width += new_allocation.x; + new_allocation.x = 0; + } - if (new_allocation.y < 0) - { - new_allocation.height += new_allocation.y; - new_allocation.y = 0; - } + if (new_allocation.y < 0) + { + new_allocation.height += new_allocation.y; + new_allocation.y = 0; + } - if (new_allocation.x + new_allocation.width > twidth) - new_allocation.width = twidth - new_allocation.x; - if (new_allocation.y + new_allocation.height > theight) - new_allocation.height = theight - new_allocation.y; + if (new_allocation.x + new_allocation.width > twidth) + new_allocation.width = twidth - new_allocation.x; + if (new_allocation.y + new_allocation.height > theight) + new_allocation.height = theight - new_allocation.y; - gdk_window_get_position (window, &tx, &ty); - new_allocation.x += tx; - x_offset += tx; - new_allocation.y += ty; - y_offset += ty; + gdk_window_get_position (window, &tx, &ty); + new_allocation.x += tx; + x_offset += tx; + new_allocation.y += ty; + y_offset += ty; - window = gdk_window_get_parent (window); + window = gdk_window_get_parent (window); } } @@ -543,35 +540,33 @@ find_widget (GtkWidget *widget, (data->x < new_allocation.x + new_allocation.width) && (data->y < new_allocation.y + new_allocation.height)) { - /* First, check if the drag is in a valid drop site in - * one of our children - */ + /* First, check if the drag is in a valid drop site in one of + our children. */ if (GTK_IS_CONTAINER (widget)) - { - struct widget_search_data new_data = *data; + { + struct widget_search_data new_data = *data; - new_data.x -= x_offset; - new_data.y -= y_offset; - new_data.foundp = false; - new_data.first = false; + new_data.x -= x_offset; + new_data.y -= y_offset; + new_data.foundp = false; + new_data.first = false; - gtk_container_forall (GTK_CONTAINER (widget), - find_widget_cb, &new_data); + gtk_container_forall (GTK_CONTAINER (widget), + find_widget_cb, &new_data); - data->foundp = new_data.foundp; - if (data->foundp) - data->data = new_data.data; - } + data->foundp = new_data.foundp; + if (data->foundp) + data->data = new_data.data; + } - /* If not, and this widget is registered as a drop site, check to - * emit "drag_motion" to check if we are actually in - * a drop site. - */ + /* If not, and this widget is registered as a drop site, check + to emit "drag_motion" to check if we are actually in a drop + site. */ if (!data->foundp) - { - data->foundp = true; - data->data = widget; - } + { + data->foundp = true; + data->data = widget; + } } } @@ -673,7 +668,7 @@ xwidget_button_1 (struct xwidget_view *view, xg_event->any.window = gtk_widget_get_window (target); g_object_ref (xg_event->any.window); /* The window will be unrefed - later by gdk_event_free. */ + later by gdk_event_free. */ xg_event->button.x = x; xg_event->button.x_root = x; @@ -711,7 +706,7 @@ xwidget_button (struct xwidget_view *view, xg_event->any.window = gtk_widget_get_window (target); g_object_ref (xg_event->any.window); /* The window will be unrefed - later by gdk_event_free. */ + later by gdk_event_free. */ if (button == 4) xg_event->scroll.direction = GDK_SCROLL_UP; else if (button == 5) @@ -741,9 +736,11 @@ xwidget_button (struct xwidget_view *view, void xwidget_motion_or_crossing (struct xwidget_view *view, const XEvent *event) { - GdkEvent *xg_event = gdk_event_new (event->type == MotionNotify ? GDK_MOTION_NOTIFY : - (event->type == LeaveNotify ? GDK_LEAVE_NOTIFY : - GDK_ENTER_NOTIFY)); + GdkEvent *xg_event = gdk_event_new (event->type == MotionNotify + ? GDK_MOTION_NOTIFY + : (event->type == LeaveNotify + ? GDK_LEAVE_NOTIFY + : GDK_ENTER_NOTIFY)); struct xwidget *model = XXWIDGET (view->model); int x; int y; @@ -761,7 +758,7 @@ xwidget_motion_or_crossing (struct xwidget_view *view, const XEvent *event) xg_event->any.window = gtk_widget_get_window (target); g_object_ref (xg_event->any.window); /* The window will be unrefed - later by gdk_event_free. */ + later by gdk_event_free. */ if (event->type == MotionNotify) { @@ -2302,9 +2299,7 @@ kill_frame_xwidget_views (struct frame *f) } for (; CONSP (rem); rem = XCDR (rem)) - { - Fdelete_xwidget_view (XCAR (rem)); - } + Fdelete_xwidget_view (XCAR (rem)); } #endif