Встроенные нативные виджеты

Emacs может отображать нативные виджеты, например виджеты GTK+ WebKit, в буферах Emacs, если он был собран с необходимыми библиотеками поддержки и запущен в графическом терминале. Чтобы проверить, поддерживает ли Emacs отображение встроенных виджетов, убедитесь, что доступна функция xwidget-internal (см. Возможности).

Чтобы отобразить встроенный виджет в буфере, сначала необходимо создать объект xwidget, а затем использовать этот объект в качестве спецификатора отображения в свойстве текста или наложения display (см. Свойство display).

Встроенные виджеты могут отправлять события, уведомляющие код Lisp об изменениях, происходящих внутри них (см. События xwidget).

Функция: make-xwidget type title width height arguments &optional buffer related

Эта функция создает и возвращает объект xwidget. Если аргумент buffer опущен или равен nil, по умолчанию используется текущий буфер. Если buffer задает несуществующий буфер, он будет создан. Аргумент type указывает тип компонента xwidget; он может принимать одно из следующих значений:

webkit

Компонент WebKit.

Аргументы width и height задают размер виджета в пикселях, а строка title — его заголовок. Аргумент related используется внутри виджета WebKit и указывает другой виджет WebKit, с которым вновь созданный виджет должен совместно использовать настройки и подпроцессы.

Возвращенный объект xwidget будет уничтожен вместе со своим буфером (см. Уничтожение буферов). Его также можно уничтожить с помощью kill-xwidget. После уничтожения объект xwidget может продолжать существовать как объект Lisp и выступать в качестве свойства display, пока на него остаются ссылки, однако большинство действий, доступных для действующих объектов xwidget, больше выполнять нельзя.

Функция: xwidgetp object

Эта функция возвращает t, если object является объектом xwidget, и nil в противном случае.

Функция: xwidget-live-p object

Эта функция возвращает t, если object является объектом xwidget, который еще не был уничтожен, и nil в противном случае.

Функция: kill-xwidget xwidget

Эта функция уничтожает xwidget, удаляя его из буфера и освобождая используемые им ресурсы оконной системы.

Функция: xwidget-plist xwidget

Эта функция возвращает список свойств xwidget.

Функция: set-xwidget-plist xwidget plist

Эта функция заменяет список свойств xwidget новым списком свойств, заданным аргументом plist.

Функция: xwidget-buffer xwidget

Эта функция возвращает буфер объекта xwidget. Если xwidget был уничтожен, она возвращает nil.

Функция: set-xwidget-buffer xwidget buffer

Эта функция устанавливает для xwidget буфер buffer.

Функция: get-buffer-xwidgets buffer

Эта функция возвращает список объектов xwidget, связанных с буфером buffer. В качестве аргумента можно указать объект буфера или строку с именем существующего буфера. Если buffer не содержит объектов xwidget, возвращается nil.

Функция: xwidget-webkit-goto-uri xwidget uri

Эта функция открывает указанный uri в заданном xwidget. Аргумент uri — это строка, задающая имя файла или URL.

Функция: xwidget-webkit-execute-script xwidget script

Эта функция запускает указанный сценарий JavaScript script в виджете браузера, заданном аргументом xwidget.

Функция: xwidget-webkit-title xwidget

Эта функция возвращает заголовок xwidget в виде строки.

Функция: xwidget-resize xwidget width height

Эта функция изменяет размер указанного xwidget на width×height пикселей.

Функция: xwidget-size-request xwidget

Эта функция возвращает желаемый размер xwidget в виде списка формы (width height). Размеры указаны в пикселях.

Функция: xwidget-info xwidget

Эта функция возвращает атрибуты xwidget в виде вектора формы [type title width height]. Обычно атрибуты задаются функцией make-xwidget при создании объекта xwidget.

Функция: set-xwidget-query-on-exit-flag xwidget flag

Эта функция позволяет настроить запрос подтверждения перед выходом из Emacs или уничтожением буфера, с которым связан xwidget. Если flag не равен nil, Emacs запросит подтверждение пользователя, в противном случае запрос не появится.

Функция: xwidget-query-on-exit-flag xwidget

Эта функция возвращает текущее значение флага запроса подтверждения перед выходом для xwidget: t или nil.

Функция: xwidget-perform-lispy-event xwidget event frame

Отправляет входное событие event объекту xwidget. Точное действие зависит от платформы. См. Входные события.

При желании можно передать кадр, в котором было сгенерировано событие, с помощью аргумента frame. В X11 клавиши-модификаторы в событиях клавиатуры не учитываются, если frame равен nil и выбранный кадр не является кадром X-Windows.

В GTK поддерживаются только события клавиатуры и функциональных клавиш. События мыши, перемещения и щелчка передаются объекту xwidget без прохождения через код Lisp, поэтому вызывать эту функцию для них не требуется.

Функция: xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around

Запускает инкрементальный поиск в виджете WebKit xwidget по строке query. Аргумент case-insensitive указывает, должен ли поиск выполняться без учета регистра, backwards определяет, выполняется ли поиск в обратном направлении, к началу документа, а wrap-around определяет, должен ли поиск продолжаться с начала документа после достижения его конца.

Если функция вызывается, когда поисковый запрос уже задан, указанный здесь запрос заменит существующий.

Чтобы остановить поиск, используйте xwidget-webkit-finish-search.

Функция: xwidget-webkit-next-result xwidget

Отображает следующий результат поиска в xwidget. Эта функция сигнализирует об ошибке, если поиск в xwidget еще не был запущен с помощью xwidget-webkit-search.

Если при вызове xwidget-webkit-search значение wrap-around было не nil, то при достижении конца документа поиск начнется заново с его начала.

Функция: xwidget-webkit-previous-result xwidget

Отображает предыдущий результат поиска в xwidget. Эта функция сигнализирует об ошибке, если поиск в xwidget еще не был запущен с помощью xwidget-webkit-search.

Если при вызове xwidget-webkit-search значение wrap-around было не nil, то при достижении начала документа поиск начнется заново с его конца.

Функция: xwidget-webkit-finish-search xwidget

Завершает поиск, запущенный с помощью xwidget-webkit-search в xwidget. Если в данный момент поиск не выполняется, функция сигнализирует об ошибке.

Функция: xwidget-webkit-load-html xwidget text &optional base-uri

Загружает строку text в xwidget, который должен быть виджетом WebKit. При отображении текста виджет xwidget обрабатывает содержащуюся в text HTML-разметку.

Необязательный аргумент base-uri, который должен быть строкой, задает абсолютное расположение веб-ресурсов, на которые ссылается text; оно используется для разрешения относительных ссылок в text.

Функция: xwidget-webkit-goto-history xwidget rel-pos

Заставляет виджет WebKit xwidget загрузить элемент истории навигации с номером rel-pos.

Если rel-pos равен нулю, вместо этого будет перезагружена текущая страница.

Функция: xwidget-webkit-back-forward-list xwidget &optional limit

Возвращает историю навигации xwidget, не более limit элементов в каждом направлении. Если аргумент не указан, по умолчанию limit равен 50.

Возвращаемое значение — список формы (back here forward), где here — текущий элемент навигации, back — список элементов, записанных WebKit до текущего элемента навигации, а forward — список элементов, записанных после текущего элемента навигации. Значения back, here и forward могут быть равны nil.

Если here равен nil, это означает, что элементы еще не записывались; если back или forward равен nil, это означает, что до или после текущего элемента соответственно нет записанной истории.

Элементы навигации сами являются списками формы (idx title uri). В этих списках idx — индекс, который можно передать функции xwidget-webkit-goto-history, title — понятный пользователю заголовок элемента, а uri — URI элемента. Обычно пользователю незачем вручную загружать uri, чтобы перейти к определенному элементу истории. Вместо этого idx следует передать в качестве индекса функции xwidget-webkit-goto-history.

Функция: xwidget-webkit-estimated-load-progress xwidget

Возвращает оценку объема данных, которые еще нужно передать, прежде чем страница, отображаемая виджетом WebKit xwidget, будет полностью загружена.

Возвращаемое значение — число с плавающей точкой в диапазоне от 0.0 до 1.0.

Функция: xwidget-webkit-set-cookie-storage-file xwidget file

Устанавливает для виджета WebKit xwidget хранение файлов cookie в файле file.

file должен быть абсолютным именем файла. Новая настройка также повлияет на все объекты xwidget, созданные с xwidget в качестве аргумента related функции make-xwidget, а также на связанные с ними виджеты.

Если эта функция не будет вызвана хотя бы один раз для xwidget или связанного с ним виджета, xwidget вообще не будет сохранять файлы cookie на диск.

Функция: xwidget-webkit-stop-loading xwidget

Прерывает передачу данных, которая еще продолжается в виджете WebKit xwidget в рамках загрузки страницы. Если страница не загружается, функция ничего не делает.