Tabulated List mode — Elisp

Режим табличного списка

Режим табличного списка — это основной режим для отображения табличных данных, то есть данных, состоящих из записей, каждая запись занимает одну строку текста с содержимым, разделенным на столбцы. Режим табличного списка предоставляет средства для красивого вывода строк и столбцов, а также сортировки строк в соответствии со значениями в каждом столбце. Он происходит от режима «Специальный» (см. Основные режимы).

Режим табличного списка предназначен для использования в качестве родительского режима более специализированным основным режимом. Примерами являются режим «Меню процессов» (см. Информация о процессах) и режим «Меню пакетов» (см. Меню пакетов в Справочном руководстве GNU Emacs).

Такой производный режим должен использовать define-derived-mode обычным способом, указав tabulated-list-mode в качестве второго аргумента (см. Производные режимы). Тело формы define-derived-mode должно указывать формат табличных данных, присваивая значения переменным, документированным ниже; в зависимости от ситуации, оно может вызвать функцию tabulated-list-init-header, которая заполнит заголовок именами столбцов.

Производный режим также должен определить команду отображения. Именно её вызывает пользователь (например, M-x list-processes), а не команду режима. Команда отображения должна создать или переключиться на буфер, включить производный режим, указать табличные данные и, наконец, вызвать tabulated-list-print для заполнения буфера.

Пользовательская опция: tabulated-list-gui-sort-indicator-asc

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

Всякий раз, когда вы меняете направление сортировки в буферах табличного списка, этот индикатор переключается между возрастающим («asc») и убывающим («desc»).

Пользовательская опция: tabulated-list-gui-sort-indicator-desc: Как и tabulated-list-gui-sort-indicator-asc, но используется, когда столбец отсортирован по убыванию.

Пользовательская опция: tabulated-list-tty-sort-indicator-asc: Как и tabulated-list-gui-sort-indicator-asc, но используется для фреймов текстового режима.

Пользовательская опция: tabulated-list-tty-sort-indicator-desc: Как и tabulated-list-tty-sort-indicator-asc, но используется, когда столбец отсортирован по убыванию.

Переменная: tabulated-list-format

Эта переменная, локальная для буфера, определяет формат данных табличного списка. Её значение должно быть вектором. Каждый элемент вектора представляет столбец данных и должен быть списком (name width sort), где

name — имя столбца (строка).
width — ширина, отводимая для столбца (целое число). Это бессмысленно для последнего столбца, который занимает всё пространство до конца строки.
sort определяет способ сортировки записей по столбцу. Если nil, столбец не может быть использован для сортировки. Если t, столбец сортируется путём сравнения строковых значений. В противном случае это должна быть предикатная функция для sort (см. Перестановка), которая принимает два аргумента с той же формой, что и элементы tabulated-list-entries (см. ниже).

Переменная: tabulated-list-entries

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

Если значение является списком, каждый элемент списка соответствует одной записи и должен иметь вид (id contents), где

id — либо nil, либо объект Lisp, идентифицирующий запись. Если последнее, курсор остаётся на той же записи при повторной сортировке записей. Сравнение выполняется с помощью equal.
contents — вектор с тем же количеством элементов, что и tabulated-list-format. Каждый элемент вектора — либо строка, которая вставляется в буфер как есть, либо список (label . properties), что означает вставку текстовой кнопки путём вызова insert-text-button с label и properties в качестве аргументов (см. Создание кнопок).
В этих строках не должно быть новых строк.

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

Переменная: tabulated-list-revert-hook: Этот обычный крючок выполняется перед восстановлением буфера табличного списка. Производный режим может добавить функцию в этот крючок для повторного вычисления tabulated-list-entries.

Переменная: tabulated-list-printer: Значение этой переменной — функция, вызываемая для вставки записи в точку, включая завершающую новую строку. Функция должна принимать два аргумента, id и contents, имеющие те же значения, что и в tabulated-list-entries. Значение по умолчанию — функция, которая вставляет запись простым способом; режим, использующий режим табличного списка более сложным образом, может указать другую функцию.

END_OF_DOCUMENT_MARKER ```

Переменная: tabulated-list-sort-key: Значение этой переменной определяет текущий ключ сортировки для буфера Табличного списка. Если это nil, сортировка не выполняется. В противном случае, оно должно иметь вид (name . flip), где name — строка, соответствующая одному из имён столбцов в tabulated-list-format, а flip, если не nil, означает инвертирование порядка сортировки.

Функция: tabulated-list-init-header

Эта функция вычисляет и устанавливает header-line-format для буфера Табличного списка (см. Строки заголовка), и назначает ключевую комбинацию для строки заголовка, чтобы позволить сортировку записей по нажатию на заголовки столбцов.

Режимы, производные от режима Табличного списка, должны вызывать эту функцию после установки вышеперечисленных переменных (в частности, только после установки tabulated-list-format).

Функция: tabulated-list-print &optional remember-pos update

Эта функция заполняет текущий буфер записями. Она должна вызываться командой вывода списка. Она очищает буфер, сортирует записи, указанные в tabulated-list-entries в соответствии с tabulated-list-sort-key, затем вызывает функцию, указанную в tabulated-list-printer для вставки каждой записи.

Если необязательный аргумент remember-pos не nil, эта функция ищет элемент id в текущей строке, если он есть, и пытается перейти к этой записи после того, как все записи будут (пере)вставлены.

Если необязательный аргумент update не nil, эта функция будет удалять или добавлять только те записи, которые изменились с момента последнего вывода. Это на несколько порядков быстрее, если большинство записей не изменились с момента последнего вызова этой функции. Единственное различие в результате заключается в том, что теги, помещенные через tabulated-list-put-tag не будут удалены из записей, которые не изменились (обычно все теги удаляются).

Функция: tabulated-list-delete-entry

Эта функция удаляет запись в позиции курсора.

Она возвращает список (id cols), где id — идентификатор удалённой записи, а cols — вектор её описателей столбцов. Она перемещает курсор в начало текущей строки. Она возвращает nil если в позиции курсора нет записи.

Обратите внимание, что эта функция изменяет только содержимое буфера; она не изменяет tabulated-list-entries.

Функция: tabulated-list-get-id &optional pos: Эта defsubst возвращает объект ID из tabulated-list-entries (если это список) или из списка, возвращаемого tabulated-list-entries (если это функция). Если опущен или nil, pos по умолчанию устанавливается в текущую позицию курсора.

Функция: tabulated-list-get-entry &optional pos: Эта defsubst возвращает объект записи из tabulated-list-entries (если это список) или из списка, возвращаемого tabulated-list-entries (если это функция). Это будет вектор для ID в позиции pos. Если в позиции pos нет записи, функция возвращает nil.

Функция: tabulated-list-header-overlay-p &optional POS: Эта defsubst возвращает не-nil, если в позиции pos находится фейковый заголовок. Фейковый заголовок используется, если tabulated-list-use-header-line равно nil для размещения имён столбцов в начале буфера. Если опущен или nil, pos по умолчанию устанавливается в point-min.

Функция: tabulated-list-put-tag tag &optional advance: Эта функция помещает tag в область заполнения текущей строки. Область заполнения может быть пустым пространством в начале строки, ширина которого определяется tabulated-list-padding. tag должна быть строкой длиной не более tabulated-list-padding. Если advance имеет ненулевое значение, эта функция перемещает курсор на одну строку вниз.

Функция: tabulated-list-clear-all-tags: Эта функция очищает все теги из области заполнения в текущем буфере.

Функция: tabulated-list-set-col col desc &optional change-entry-data

Эта функция изменяет запись табличного списка в позиции курсора, устанавливая col в desc. col — номер столбца для изменения или имя столбца для изменения. desc — новый описатель столбца, который вставляется через tabulated-list-print-col.

Если change-entry-data имеет ненулевое значение, эта функция изменяет базовые данные (обычно описатель столбца в списке tabulated-list-entries) устанавливая описатель столбца вектора в desc.