42.19 嵌入式原生组件

当 Emacs 编译时包含必要的支持库,并且运行在图形终端下时,能够在 Emacs 缓冲区中显示原生组件,例如 GTK+ WebKit 组件。要检测 Emacs 是否支持显示嵌入式组件,可检查 xwidget-internal 特性是否可用(see 功能)。

要在缓冲区中显示嵌入式组件,必须先创建一个 xwidget 对象,然后将该对象用作 display 文本属性或叠加属性中的显示规格(see display 属性)。

嵌入式组件可以发送事件,向 Lisp 代码通知其内部发生的变化。(see Xwidget 事件)。

Function: make-xwidget type title width height arguments &optional buffer related

该函数创建并返回一个 xwidget 对象。如果 buffer 省略或为 nil,则默认为当前缓冲区。如果 buffer 是一个不存在的缓冲区名称,将会自动创建。type 标识 xwidget 组件的类型,可以是下列之一:

webkit

WebKit 组件。

参数 widthheight 以像素为单位指定组件大小,title 是一个字符串,指定组件标题。related 由 WebKit 组件内部使用,用于指定一个已有的 WebKit 组件,新建组件将与其共享设置和子进程。

返回的 xwidget 会随其所属缓冲区一同被销毁(see 杀死缓冲区)。你也可以使用 kill-xwidget 手动销毁它。一旦被销毁,xwidget 可能仍会作为 Lisp 对象存在,并继续充当 display 属性,直到所有对它的引用消失;但大多数可对活跃 xwidget 执行的操作将不再可用。

Function: xwidgetp object

如果 object 是 xwidget,该函数返回 t,否则返回 nil

Function: xwidget-live-p object

如果 object 是尚未被销毁的 xwidget,该函数返回 t,否则返回 nil

Function: kill-xwidget xwidget

该函数销毁 xwidget,将其从缓冲区中移除并释放它占用的窗口系统资源。

Function: xwidget-plist xwidget

该函数返回 xwidget 的属性列表。

Function: set-xwidget-plist xwidget plist

该函数将 xwidget 的属性列表替换为 plist 指定的新属性列表。

Function: xwidget-buffer xwidget

该函数返回 xwidget 所属的缓冲区。如果 xwidget 已被销毁,则返回 nil

Function: set-xwidget-buffer xwidget buffer

该函数将 xwidget 的缓冲区设置为 buffer

Function: get-buffer-xwidgets buffer

该函数返回与缓冲区 buffer 关联的 xwidget 对象列表;buffer 可以是缓冲区对象或已存在缓冲区的名称(字符串)。如果 buffer 不包含任何 xwidget,返回值为 nil

Function: xwidget-webkit-goto-uri xwidget uri

该函数在指定的 xwidget 中浏览给定的 uriuri 是一个字符串,可以是文件名或 URL。

Function: xwidget-webkit-execute-script xwidget script

该函数让 xwidget 指定的浏览器组件执行指定的 JavaScript 脚本 script

Function: xwidget-webkit-title xwidget

该函数以字符串形式返回 xwidget 的标题。

Function: xwidget-resize xwidget width height

该函数将指定的 xwidget 大小调整为宽 width、高 height 像素。

Function: xwidget-size-request xwidget

该函数以 (width height) 形式的列表返回 xwidget 的期望尺寸,单位为像素。

Function: xwidget-info xwidget

该函数以 [type title width height] 形式的向量返回 xwidget 的属性。这些属性通常在调用 make-xwidget 创建 xwidget 时确定。

Function: set-xwidget-query-on-exit-flag xwidget flag

该函数可设置 Emacs 在退出或销毁与 xwidget 关联的缓冲区前,向用户请求确认。如果 flag 为非 nil,Emacs 会进行询问,否则不会。

Function: xwidget-query-on-exit-flag xwidget

该函数返回 xwidget 的退出询问标志当前设置,为 tnil

Function: xwidget-perform-lispy-event xwidget event frame

xwidget 发送输入事件 event。具体行为与平台相关。See 输入事件

你可以通过 frame 可选地传入事件产生的框架。在 X11 下,如果 framenil 且当前选中框架不是 X 窗口框架,按键事件中的修饰键将被忽略。

在 GTK 下,仅支持键盘和功能键事件。鼠标、移动、点击事件会直接分发给 xwidget,不经过 Lisp 代码,因此通常不需要调用此函数。

Function: xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around

在 WebKit 组件 xwidget 中以字符串 query 为关键词开始增量搜索。case-insensitive 表示搜索是否忽略大小写,backwards 决定是否向文档开头反向搜索,wrap-around 决定搜索到达文档末尾时是否循环。

如果调用此函数时已有搜索正在进行,新的关键词会替换原有关键词。

使用 xwidget-webkit-finish-search 停止搜索。

Function: xwidget-webkit-next-result xwidget

xwidget 中显示下一个搜索结果。如果尚未通过 xwidget-webkit-searchxwidget 中启动搜索,该函数会报错。

如果调用 xwidget-webkit-searchwrap-around 为非 nil,搜索到达文档末尾后会从头重新开始。

Function: xwidget-webkit-previous-result xwidget

xwidget 中显示上一个搜索结果。如果尚未通过 xwidget-webkit-searchxwidget 中启动搜索,该函数会报错。

如果调用 xwidget-webkit-searchwrap-around 为非 nil,搜索到达文档开头后会从末尾重新开始。

Function: xwidget-webkit-finish-search xwidget

结束在 xwidget 中由 xwidget-webkit-search 启动的搜索操作。如果当前没有正在进行的搜索,该函数会报错。

Function: xwidget-webkit-load-html xwidget text &optional base-uri

将字符串 text 加载到 xwidget 中,该组件必须是 WebKit 类型的 xwidget。text 中的所有 HTML 标记都会在渲染时被 xwidget 处理。

可选参数 base-uri 为字符串,指定 text 中引用的网络资源的绝对位置,用于解析 text 中的相对链接。

Function: xwidget-webkit-goto-history xwidget rel-pos

让 WebKit 组件 xwidget 加载其浏览历史中的第 rel-pos 项。

如果 rel-pos 为 0,则重新加载当前页面。

Function: xwidget-webkit-back-forward-list xwidget &optional limit

返回 xwidget 的浏览历史,每个方向最多返回 limit 条。若未指定,limit 默认为 50。

返回值为 (back here forward) 形式的列表,其中 here 是当前浏览项,back 是当前项之前 WebKit 记录的历史列表,forward 是当前项之后记录的历史列表。backhereforward 均可为 nil

herenil 时,表示尚未记录任何项;如果 backforwardnil,分别表示当前项之前或之后无历史记录。

浏览项本身是 (idx title uri) 形式的列表。其中 idx 是可传给 xwidget-webkit-goto-history 的索引,title 是人类可读的标题,uri 是该项地址。用户通常无需手动加载 uri 访问历史项,而应将 idx 作为索引传给 xwidget-webkit-goto-history

Function: xwidget-webkit-estimated-load-progress xwidget

返回 WebKit 组件 xwidget 显示页面完全加载前,剩余待传输数据的估算比例。

返回值为 0.0 到 1.0 之间的浮点数。

Function: xwidget-webkit-set-cookie-storage-file xwidget file

让 WebKit 组件 xwidget 将 Cookie 保存到文件 file 中。

file 必须是绝对文件名。新设置会影响所有以该 xwidget 作为 related 参数创建的 xwidget,以及这些组件关联的其他组件。

如果未对 xwidget 或其关联组件至少调用过一次此函数,xwidget 将不会在磁盘上保存任何 Cookie。

Function: xwidget-webkit-stop-loading xwidget

终止 WebKit 组件 xwidget 中仍在进行的页面加载数据传输。如果当前没有正在加载的页面,该函数不执行任何操作。