From 29698cd59a85c7c47f6f684c56a42d894af5f4bc Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Wed, 18 Oct 2023 17:30:28 +0300 Subject: [PATCH 01/10] Deprecate argument browser in ffi-within-renderer-thread. --- source/browser.lisp | 6 +----- source/foreign-interface.lisp | 7 ++++--- source/prompt-buffer.lisp | 11 +++++------ source/renderer/gtk.lisp | 6 ++---- source/start.lisp | 4 +--- 5 files changed, 13 insertions(+), 21 deletions(-) diff --git a/source/browser.lisp b/source/browser.lisp index 7c4f129b130..4250524d392 100644 --- a/source/browser.lisp +++ b/source/browser.lisp @@ -320,11 +320,7 @@ A list of strings is returned, as to comply with `uiop:launch-program' or "Run BODY from a new thread when renderer is ready. `ffi-within-renderer-thread' runs its body on the renderer thread when it's idle, so it should do the job." - `(ffi-within-renderer-thread - browser - (lambda () - (run-thread ,thread-name - ,@body)))) + `(ffi-within-renderer-thread (lambda () (run-thread ,thread-name ,@body)))) (defmethod finalize ((browser browser) urls startup-timestamp) "Run `after-init-hook' then BROWSER's `startup'." diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index cfec0507fac..a9b81830436 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -230,9 +230,10 @@ See also `ffi-generated-input-event-p'.") (define-ffi-generic ffi-generated-input-event-p (window event) "Return non-nil if EVENT was generated by `ffi-generate-input-event'.") -(define-ffi-generic ffi-within-renderer-thread (browser thunk) - "Run THUNK (a lambda of no argument) from the renderer's thread. -This is useful in particular for renderer-specific functions that cannot be run on random threads." +(define-ffi-generic ffi-within-renderer-thread (thunk) + "Run THUNK (a lambda of no argument) in the renderer's thread. +It is particularly useful for renderer procedures required to be executed in +specific threads." (funcall thunk)) (define-ffi-generic ffi-kill-browser (browser) diff --git a/source/prompt-buffer.lisp b/source/prompt-buffer.lisp index 86f73a19f7a..01e54ad5707 100644 --- a/source/prompt-buffer.lisp +++ b/source/prompt-buffer.lisp @@ -704,14 +704,13 @@ See the documentation of `prompt-buffer' to know more about the options." (setf (getf args :prompt) (string-right-trim (uiop:strcat ":" serapeum:whitespace) prompt-text)))) (let ((prompt-object-channel (make-channel 1))) (ffi-within-renderer-thread - *browser* (lambda () - (let ((prompt-buffer (apply #'make-instance 'prompt-buffer + (let ((prompt-buffer (apply #'make-instance + 'prompt-buffer (append args - (list - :window (current-window) - :result-channel (make-channel) - :interrupt-channel (make-channel)))))) + (list :window (current-window) + :result-channel (make-channel) + :interrupt-channel (make-channel)))))) (calispel:! prompt-object-channel prompt-buffer)))) (let ((new-prompt (calispel:? prompt-object-channel))) (wait-on-prompt-buffer new-prompt))))) diff --git a/source/renderer/gtk.lisp b/source/renderer/gtk.lisp index 6de68ae18f0..bd73d34f565 100644 --- a/source/renderer/gtk.lisp +++ b/source/renderer/gtk.lisp @@ -170,10 +170,8 @@ See https://github.com/atlas-engineer/nyxt/issues/740") (with-protect ("Error on GTK thread: ~a" :condition) ,@body))) -(defmethod ffi-within-renderer-thread ((browser gtk-browser) thunk) - (declare (ignore browser)) - (within-gtk-thread - (funcall thunk))) +(defmethod ffi-within-renderer-thread (thunk) + (within-gtk-thread (funcall thunk))) (defun %within-renderer-thread (thunk) "If the current thread is the renderer thread, execute THUNK with `funcall'. diff --git a/source/start.lisp b/source/start.lisp index 6bdc8a34ad4..11fabd7d4ea 100644 --- a/source/start.lisp +++ b/source/start.lisp @@ -296,9 +296,7 @@ It takes URL-STRINGS so that the URL argument can be `cl-read' in case (if urls (log:info "Externally requested URL(s): ~{~a~^, ~}" urls) (log:info "Externally pinged.")) - (ffi-within-renderer-thread - *browser* - (lambda () (open-urls urls))) + (ffi-within-renderer-thread (lambda () (open-urls urls))) urls)) (defun listen-socket () From ca837101e48bfea9206f9e2cb7628ac58178f376 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Wed, 18 Oct 2023 17:35:34 +0300 Subject: [PATCH 02/10] Rename method to finalize-startup. --- source/browser.lisp | 2 +- source/foreign-interface.lisp | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/source/browser.lisp b/source/browser.lisp index 4250524d392..f15da410af8 100644 --- a/source/browser.lisp +++ b/source/browser.lisp @@ -322,7 +322,7 @@ A list of strings is returned, as to comply with `uiop:launch-program' or idle, so it should do the job." `(ffi-within-renderer-thread (lambda () (run-thread ,thread-name ,@body)))) -(defmethod finalize ((browser browser) urls startup-timestamp) +(defmethod finalize-startup ((browser browser) urls startup-timestamp) "Run `after-init-hook' then BROWSER's `startup'." ;; `messages-appender' requires `*browser*' to be initialized. (unless (find-if (sera:eqs 'messages-appender) (log4cl:all-appenders) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index a9b81830436..38f3257561b 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -242,8 +242,9 @@ This often translates in the termination of the \"main loop\" associated to the (define-ffi-generic ffi-initialize (browser urls startup-timestamp) "Renderer-specific initialization. -When done, call `call-next-method' to finalize the startup." - (finalize browser urls startup-timestamp)) +A specialization of this method must call `call-next-method' to conclude the +startup routine." + (finalize-startup browser urls startup-timestamp)) (define-ffi-generic ffi-inspector-show (buffer) "Show the renderer built-in inspector.") From f19a6cdb93760b915d8145fde720484e7f32ec46 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Wed, 18 Oct 2023 18:09:16 +0300 Subject: [PATCH 03/10] Remove ffi-muted-p. Mistakenly introduced in 09042ac5628f5bb2c1b4b133d578804032b0143f. --- source/foreign-interface.lisp | 3 --- source/renderer/gtk.lisp | 4 ---- 2 files changed, 7 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 38f3257561b..5b42e0311e8 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -285,9 +285,6 @@ Setf-able, where the languages value is a list of strings like '(\"en_US\" (define-ffi-generic ffi-focused-p (buffer) "Return non-nil if the BUFFER widget is the one with focus (currently displayed).") -(define-ffi-generic ffi-muted-p (buffer) - "Return non-nil if the BUFFER cannot produce any sound.") - (define-ffi-generic ffi-tracking-prevention (buffer) "Return if WebKit-specific Intelligent Tracking Prevention (ITP) is enabled. Setf-able." diff --git a/source/renderer/gtk.lisp b/source/renderer/gtk.lisp index bd73d34f565..27a168524b5 100644 --- a/source/renderer/gtk.lisp +++ b/source/renderer/gtk.lisp @@ -2120,10 +2120,6 @@ As a second value, return the current buffer index starting from 0." (define-ffi-method ffi-focused-p ((buffer gtk-buffer)) (gtk:gtk-widget-is-focus (gtk-object buffer))) -(define-ffi-method ffi-muted-p ((buffer gtk-buffer)) - #+webkit2-mute - (webkit:webkit-web-view-is-muted (gtk-object buffer))) - (define-ffi-method ffi-tracking-prevention ((buffer gtk-buffer)) #+webkit2-tracking (webkit:webkit-website-data-manager-get-itp-enabled From aa20d77fb2a5a1a0e288ff5111d74cab0b925327 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Wed, 6 Dec 2023 17:01:12 +0200 Subject: [PATCH 04/10] foreign-interface: Delete redundant warnings. --- source/foreign-interface.lisp | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 5b42e0311e8..06136801906 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -373,12 +373,10 @@ Return the text cut." (ps:chain active-element (set-selection-range 0 (ps:@ active-element value length)))))))) (define-ffi-generic ffi-buffer-undo (buffer) - "Undo the last text edit performed in BUFFER's web view." - (echo-warning "Undoing edits is not yet implemented for this renderer.")) + "Undo the last text edit performed in BUFFER's web view.") (define-ffi-generic ffi-buffer-redo (buffer) - "Redo the last undone text edit performed in BUFFER's web view." - (echo-warning "Redoing edits is not yet implemented for this renderer.")) + "Redo the last undone text edit performed in BUFFER's web view.") ;; TODO: Move to alists for arbitrary number of params? (defvar *context-menu-commands* (make-hash-table :test #'equal) From 8dea1a720c54f172397268832e9d10c99d5b0f21 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Fri, 15 Dec 2023 16:13:54 +0200 Subject: [PATCH 05/10] foreign-interface: Explicitly declare methods. Highlights that renderer-specific objects inherit from T. Therefore, any specialization is more specific that the fallback method defined in this file. --- source/foreign-interface.lisp | 36 ++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 06136801906..8043ced3e10 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -59,13 +59,15 @@ This is used to set the BUFFER `url' slot.") (define-ffi-generic ffi-window-make (browser) "Return a `window' object, ready for display. The renderer specialization must handle the widget initialization." - (make-instance 'window)) + (:method ((browser t)) + (make-instance 'window))) (define-ffi-generic ffi-window-to-foreground (window) "Show WINDOW in the foreground. The specialized method may call `call-next-method' to set WINDOW as the `last-active-window'." - (setf (slot-value *browser* 'last-active-window) window)) + (:method ((window t)) + (setf (slot-value *browser* 'last-active-window) window))) (define-ffi-generic ffi-window-title (window) "Return as a string the title of the window. @@ -192,7 +194,7 @@ PROXY-URL is a `quri:uri' and IGNORE-HOSTS a list of strings." (define-ffi-generic ffi-buffer-zoom-level (buffer) "Return the zoom level of the document. Setf-able." - (:method (buffer) + (:method ((buffer t)) (ps-eval :buffer buffer (ps:chain document body style zoom))) (:setter-p t)) (defmethod (setf ffi-buffer-zoom-level) (value (buffer buffer)) @@ -234,7 +236,8 @@ See also `ffi-generated-input-event-p'.") "Run THUNK (a lambda of no argument) in the renderer's thread. It is particularly useful for renderer procedures required to be executed in specific threads." - (funcall thunk)) + (:method ((thunk t)) + (funcall thunk))) (define-ffi-generic ffi-kill-browser (browser) "Terminate the renderer. @@ -244,7 +247,8 @@ This often translates in the termination of the \"main loop\" associated to the "Renderer-specific initialization. A specialization of this method must call `call-next-method' to conclude the startup routine." - (finalize-startup browser urls startup-timestamp)) + (:method ((browser t) urls startup-timestamp) + (finalize-startup browser urls startup-timestamp))) (define-ffi-generic ffi-inspector-show (buffer) "Show the renderer built-in inspector.") @@ -252,20 +256,22 @@ startup routine." (define-ffi-generic ffi-print-status (window html-body) "Display status buffer in WINDOW according to HTML-BODY. The `style' of the `status-buffer' is honored." - (with-slots (status-buffer) window - (html-write (spinneret:with-html-string - (:head (:nstyle (style status-buffer))) - (:body (:raw html-body))) - status-buffer))) + (:method ((window t) html-body) + (with-slots (status-buffer) window + (html-write (spinneret:with-html-string + (:head (:nstyle (style status-buffer))) + (:body (:raw html-body))) + status-buffer)))) (define-ffi-generic ffi-print-message (window html-body) "Print HTML-BODY in the WINDOW's message buffer. The `style' of the `message-buffer' is honored." - (with-slots (message-buffer) window - (html-write (spinneret:with-html-string - (:head (:nstyle (style message-buffer))) - (:body (:raw html-body))) - message-buffer))) + (:method ((window t) html-body) + (with-slots (message-buffer) window + (html-write (spinneret:with-html-string + (:head (:nstyle (style message-buffer))) + (:body (:raw html-body))) + message-buffer)))) (define-ffi-generic ffi-display-url (browser url) "Return URL as a human-readable string. From e4820beb9e8d02d76d32f0b9de5ebbf8e50644fa Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Fri, 15 Dec 2023 16:22:53 +0200 Subject: [PATCH 06/10] foreign-interface: Define signals with define-ffi-generic. Should have been in commit df5fc4210243f3717562660549e45d5628229407. --- source/foreign-interface.lisp | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 8043ced3e10..3c0c0dbd65b 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -441,8 +441,7 @@ Example: ;;; Signals -(export-always 'on-signal-notify-uri) -(define-generic on-signal-notify-uri (object url) +(define-ffi-generic on-signal-notify-uri (object url) "Invoked when URL changes in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) no-url) @@ -461,8 +460,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-notify-title) -(define-generic on-signal-notify-title (object title) +(define-ffi-generic on-signal-notify-title (object title) "Invoked when page TITLE is set in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) no-title) @@ -476,8 +474,7 @@ Dispatches on buffers and modes." title)) ;; See https://webkitgtk.org/reference/webkit2gtk/stable/WebKitWebView.html#WebKitLoadEvent -(export-always 'on-signal-load-started) -(define-generic on-signal-load-started (object url) +(define-ffi-generic on-signal-load-started (object url) "Invoked when URL starts loading in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -486,8 +483,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-load-redirected) -(define-generic on-signal-load-redirected (object url) +(define-ffi-generic on-signal-load-redirected (object url) "Invoked when the request gets redirected to URL in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -496,8 +492,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-load-canceled) -(define-generic on-signal-load-canceled (object url) +(define-ffi-generic on-signal-load-canceled (object url) "Invoked when URL loading is canceled in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -506,8 +501,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-load-committed) -(define-generic on-signal-load-committed (object url) +(define-ffi-generic on-signal-load-committed (object url) "Invoked when URL loading is approved in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -516,8 +510,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-load-finished) -(define-generic on-signal-load-finished (object url) +(define-ffi-generic on-signal-load-finished (object url) "Invoked when done loading URL in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -528,8 +521,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-load-failed) -(define-generic on-signal-load-failed (object url) +(define-ffi-generic on-signal-load-failed (object url) "Invoked when URL loading has failed in OBJECT. Dispatches on buffers and modes." (:method ((buffer buffer) url) @@ -538,8 +530,7 @@ Dispatches on buffers and modes." (:method ((mode mode) url) url)) -(export-always 'on-signal-button-press) -(define-generic on-signal-button-press (object button-key) +(define-ffi-generic on-signal-button-press (object button-key) "Invoked on BUTTON-KEY press. Dispatches on buffers and modes." (:method ((buffer buffer) button-key) @@ -549,8 +540,7 @@ Dispatches on buffers and modes." (declare (ignorable button-key)) nil)) -(export-always 'on-signal-key-press) -(define-generic on-signal-key-press (object key) +(define-ffi-generic on-signal-key-press (object key) "Invoked on KEY press. Dispatches on buffers and modes." (:method ((buffer buffer) key) From f5f373a1c026f7e513dab037ff2f5712aaaf3ed2 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Fri, 15 Dec 2023 22:17:53 +0200 Subject: [PATCH 07/10] foreign-interface: Refactor ffi-window-active. Place the primary method after the around method to ease readability. Refactor docstring. --- source/foreign-interface.lisp | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 3c0c0dbd65b..0e7af416336 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -76,19 +76,18 @@ Setf-able." (:setter-p t)) (define-ffi-generic ffi-window-active (browser) - "The primary method returns the focused window as per the -renderer. + "Return the focused window. -The `:around' method automatically ensures that the result is set to -`last-active-window'. +The specialized method must fallback on the primary method below, as to account +for the case when the renderer reports that none of the windows are focused. -The specialized method may call `call-next-method' to return a sensible fallback window." - (:method ((browser t)) - (or (slot-value browser 'last-active-window) - (first (window-list)))) +The `:around' method ensures that `last-active-window' is set." (:method :around ((browser t)) (setf (slot-value browser 'last-active-window) - (call-next-method)))) + (call-next-method))) + (:method ((browser t)) + (or (slot-value browser 'last-active-window) + (first (window-list))))) (define-ffi-generic ffi-window-set-buffer (window buffer &key focus) "Set the BUFFER's widget to display in WINDOW.") From 99c691f16c0265503288bc1e0372ecdfa5f44d5c Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Fri, 15 Dec 2023 22:58:40 +0200 Subject: [PATCH 08/10] Refactor ffi-focus-prompt-buffer. It doesn't need window as its argument, since prompt buffer objects have a window slot. --- source/buffer.lisp | 2 +- source/foreign-interface.lisp | 4 ++-- source/renderer/gtk.lisp | 3 +-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/source/buffer.lisp b/source/buffer.lisp index f952d190b51..7d2d9d9f50f 100644 --- a/source/buffer.lisp +++ b/source/buffer.lisp @@ -1486,7 +1486,7 @@ is listed first." (prog1 (set-current-buffer (current-buffer)) (ps-eval :buffer prompt-buffer (setf (ps:@ (nyxt/ps:qs document "*") style opacity) "0.5"))) - (prog1 (ffi-focus-prompt-buffer (current-window) prompt-buffer) + (prog1 (ffi-focus-prompt-buffer prompt-buffer) (ps-eval :buffer prompt-buffer (setf (ps:@ (nyxt/ps:qs document "*") style opacity) "1")))))) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 0e7af416336..7f21c30930f 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -92,8 +92,8 @@ The `:around' method ensures that `last-active-window' is set." (define-ffi-generic ffi-window-set-buffer (window buffer &key focus) "Set the BUFFER's widget to display in WINDOW.") -(define-ffi-generic ffi-focus-prompt-buffer (window prompt-buffer) - "Focus PROMPT-BUFFER in WINDOW.") +(define-ffi-generic ffi-focus-prompt-buffer (prompt-buffer) + "Return PROMPT-BUFFER and focus it as a side effect.") (define-ffi-generic ffi-window-add-panel-buffer (window buffer side) "Make widget for panel BUFFER and add it to the WINDOW widget. diff --git a/source/renderer/gtk.lisp b/source/renderer/gtk.lisp index 27a168524b5..ddd2f84952b 100644 --- a/source/renderer/gtk.lisp +++ b/source/renderer/gtk.lisp @@ -1260,8 +1260,7 @@ the `active-buffer'." (gtk:gtk-widget-grab-focus (gtk-object (nyxt::active-buffer (window buffer)))) (gtk:gtk-widget-grab-focus (prompt-buffer-view (window buffer))))) -(define-ffi-method ffi-focus-prompt-buffer ((window gtk-window) - (prompt-buffer prompt-buffer)) +(define-ffi-method ffi-focus-prompt-buffer ((prompt-buffer prompt-buffer)) "Focus PROMPT-BUFFER in WINDOW." (gtk:gtk-widget-grab-focus (prompt-buffer-view (window prompt-buffer))) prompt-buffer) From 67d20beab91ee2d5e82713d29cf8e3dd316eb789 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Fri, 15 Dec 2023 22:59:42 +0200 Subject: [PATCH 09/10] renderer/gtk: Leverage ffi-focus-prompt-buffer. --- source/renderer/gtk.lisp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/renderer/gtk.lisp b/source/renderer/gtk.lisp index ddd2f84952b..70a280c3f6b 100644 --- a/source/renderer/gtk.lisp +++ b/source/renderer/gtk.lisp @@ -1258,7 +1258,7 @@ the `active-buffer'." (list -1 height)) (if (eql 0 height) (gtk:gtk-widget-grab-focus (gtk-object (nyxt::active-buffer (window buffer)))) - (gtk:gtk-widget-grab-focus (prompt-buffer-view (window buffer))))) + (ffi-focus-prompt-buffer buffer))) (define-ffi-method ffi-focus-prompt-buffer ((prompt-buffer prompt-buffer)) "Focus PROMPT-BUFFER in WINDOW." From 8af6b3c7c0aa4dd9160e22f458b40bf608e2f9d9 Mon Sep 17 00:00:00 2001 From: "Andre A. Gomes" Date: Wed, 18 Oct 2023 19:32:41 +0300 Subject: [PATCH 10/10] foreign-interface: Review docstrings. --- source/foreign-interface.lisp | 75 +++++++++++++++-------------------- 1 file changed, 32 insertions(+), 43 deletions(-) diff --git a/source/foreign-interface.lisp b/source/foreign-interface.lisp index 7f21c30930f..45317f8ebcf 100644 --- a/source/foreign-interface.lisp +++ b/source/foreign-interface.lisp @@ -33,45 +33,37 @@ If the `:setter-p' option is non-nil, then a dummy setf method is defined." (declare (ignore value ,@arguments))))))))) (define-ffi-generic ffi-window-delete (window) - "Delete WINDOW, possibly freeing the associated widgets. -After this call, the window should not be displayed.") + "Delete WINDOW.") (define-ffi-generic ffi-window-fullscreen (window) - "Make WINDOW fullscreen. -Removes all the Nyxt interface element and leaves the open page as the only -thing on the screen.") + "Set fullscreen WINDOW state on.") (define-ffi-generic ffi-window-unfullscreen (window) - "Un-fullscreen the WINDOW.") + "Set fullscreen WINDOW state off.") (define-ffi-generic ffi-window-maximize (window) - "Make the WINDOW to fill the screen. -Usually possible via desktop environment interface too.") + "Set WINDOW to a maximized state.") (define-ffi-generic ffi-window-unmaximize (window) - "Switch the WINDOW to \"windowed\" display. -May or may not fill the screen.") + "Set WINDOW to an unmaximized state.") (define-ffi-generic ffi-buffer-url (buffer) - "Return the `quri:uri' associated with the BUFFER. + "Return the URL associated with BUFFER as a `quri:uri'. This is used to set the BUFFER `url' slot.") (define-ffi-generic ffi-buffer-title (buffer) - "Return as a string the title of the document (or web page) showing in BUFFER.") + "Return a string corresponding to the BUFFER's title.") (define-ffi-generic ffi-window-make (browser) - "Return a `window' object, ready for display. -The renderer specialization must handle the widget initialization." + "Return a `window' and display it." (:method ((browser t)) (make-instance 'window))) (define-ffi-generic ffi-window-to-foreground (window) "Show WINDOW in the foreground. -The specialized method may call `call-next-method' to set -WINDOW as the `last-active-window'." +The specialized method must invoke `call-next-method' last." (:method ((window t)) (setf (slot-value *browser* 'last-active-window) window))) (define-ffi-generic ffi-window-title (window) - "Return as a string the title of the window. -It is the title that's often used by the window manager to decorate the window. + "Return a string corresponding to the WINDOW's title. Setf-able." (:setter-p t)) @@ -90,87 +82,85 @@ The `:around' method ensures that `last-active-window' is set." (first (window-list))))) (define-ffi-generic ffi-window-set-buffer (window buffer &key focus) - "Set the BUFFER's widget to display in WINDOW.") + "Return BUFFER and display it in WINDOW as a side effect.") (define-ffi-generic ffi-focus-prompt-buffer (prompt-buffer) "Return PROMPT-BUFFER and focus it as a side effect.") (define-ffi-generic ffi-window-add-panel-buffer (window buffer side) - "Make widget for panel BUFFER and add it to the WINDOW widget. + "Add panel BUFFER to WINDOW. SIDE is one of `:left' or `:right'.") (define-ffi-generic ffi-window-delete-panel-buffer (window buffer) - "Unbind the panel BUFFER widget from WINDOW.") + "Delete the panel BUFFER from WINDOW.") (define-ffi-generic ffi-height (object) - "Return the OBJECT height in pixels as a number. + "Return the OBJECT's height in pixels. Dispatches over `window' and classes inheriting from `buffer'. Usually setf-able." (:setter-p t)) (define-ffi-generic ffi-width (object) - "Return the OBJECT width in pixels as a number. + "Return the OBJECT's width in pixels. Dispatches over `window' and classes inheriting from `buffer'. Usually setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-make (buffer) - "Make BUFFER widget.") + "Return BUFFER and display it.") (define-ffi-generic ffi-buffer-delete (buffer) - "Delete BUFFER widget.") + "Delete BUFFER.") (define-ffi-generic ffi-buffer-load (buffer url) "Load URL into BUFFER through the renderer.") (define-ffi-generic ffi-buffer-load-html (buffer html-content url) "Load HTML-CONTENT into BUFFER through the renderer. -If URL is not nil, relative URLs are resolved against it.") +When URL is non-nil, relative URLs are resolved against it.") (define-ffi-generic ffi-buffer-load-alternate-html (buffer html-content content-url url) "Load HTML-CONTENT for CONTENT-URL into BUFFER through the renderer. Like `ffi-buffer-load-html', except that it doesn't influence the BUFFER history or CSS/HTML cache.") (define-ffi-generic ffi-buffer-evaluate-javascript (buffer javascript &optional world-name) - "Evaluate JAVASCRIPT in the BUFFER web view. -See also `ffi-buffer-evaluate-javascript-async'.") + "Evaluate JAVASCRIPT, encoded as a string, in BUFFER.") (define-ffi-generic ffi-buffer-evaluate-javascript-async (buffer javascript &optional world-name) - "Same as `ffi-buffer-evaluate-javascript' but don't wait for -the termination of the JavaScript execution.") + "Asynchronous version of `ffi-buffer-evaluate-javascript'.") (define-ffi-generic ffi-buffer-add-user-style (buffer style) - "Apply the CSS style to the BUFFER web view.") + "Apply the CSS style to BUFFER.") (define-ffi-generic ffi-buffer-remove-user-style (buffer style) "Remove the STYLE installed with `ffi-buffer-add-user-style'.") (define-ffi-generic ffi-buffer-add-user-script (buffer user-script) - "Install the JAVASCRIPT into the BUFFER web view.") + "Install the JAVASCRIPT into the BUFFER web view.") (define-ffi-generic ffi-buffer-remove-user-script (buffer script) "Remove the SCRIPT installed with `ffi-buffer-add-user-script'.") (define-ffi-generic ffi-buffer-javascript-enabled-p (buffer) - "Return whether JavaScript can run, as boolean. + "Return non-nil when JavaScript is enabled in BUFFER. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-javascript-markup-enabled-p (buffer) - "Return whether JavaScript can alter the page contents, as boolean. + "Return non-nil when JavaScript can mutate the BUFFER' contents. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-smooth-scrolling-enabled-p (buffer) - "Return whether the smooth scrolling is enabled, as boolean. + "Return non-nil when smooth scrolling is enabled in BUFFER. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-media-enabled-p (buffer) - "Return whether video and audio playback is enabled, as boolean. + "Return non-nil when video and audio playback are enabled in BUFFER. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-webgl-enabled-p (buffer) - "Return whether WebGL is enabled, as boolean. + "Return non-nil when WebGL is enabled in BUFFER. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-auto-load-image-enabled-p (buffer) - "Return whether images are displayed, as boolean. + "Return non-nil when images are displayed in BUFFER. Setf-able." (:setter-p t)) (define-ffi-generic ffi-buffer-sound-enabled-p (buffer) - "Return whether the BUFFER has sound enabled, as boolean. + "Return non-nil when the sound is enabled in BUFFER. Setf-able." (:setter-p t)) @@ -229,7 +219,7 @@ spontaneous events from programmed ones. See also `ffi-generated-input-event-p'.") (define-ffi-generic ffi-generated-input-event-p (window event) - "Return non-nil if EVENT was generated by `ffi-generate-input-event'.") + "Return non-nil when EVENT was generated by `ffi-generate-input-event'.") (define-ffi-generic ffi-within-renderer-thread (thunk) "Run THUNK (a lambda of no argument) in the renderer's thread. @@ -239,8 +229,7 @@ specific threads." (funcall thunk))) (define-ffi-generic ffi-kill-browser (browser) - "Terminate the renderer. -This often translates in the termination of the \"main loop\" associated to the widget engine.") + "Terminate the renderer process.") (define-ffi-generic ffi-initialize (browser urls startup-timestamp) "Renderer-specific initialization. @@ -288,7 +277,7 @@ Setf-able, where the languages value is a list of strings like '(\"en_US\" (:setter-p t)) (define-ffi-generic ffi-focused-p (buffer) - "Return non-nil if the BUFFER widget is the one with focus (currently displayed).") + "Return non-nil when BUFFER is focused.") (define-ffi-generic ffi-tracking-prevention (buffer) "Return if WebKit-specific Intelligent Tracking Prevention (ITP) is enabled.