API выбора областей листа

TXLSWorksheet и TXLSXWorksheet предоставляют одинаковые методы с учетом областей окна для чтения или замены выделенных областей ячеек и диапазонов

Общие типы и методы

TXLSPanePosition = (xlspTopLeft, xlspTopRight,
  xlspBottomLeft, xlspBottomRight);
TXLSSelectedAreas = array of WideString;

function GetSelectedAreas(APane: TXLSPanePosition;
  out ActiveAreaIndex: Integer): TXLSSelectedAreas;
function SelectAreas(APane: TXLSPanePosition;
  const Areas: array of WideString;
  ActiveAreaIndex: Integer = 0): Boolean;
function TryGetWindowScroll(APane: TXLSPanePosition;
  out ARow, ACol: Integer): Boolean;
function ScrollWindow(APane: TXLSPanePosition;
  ARow, ACol: Integer): Boolean;

Текст области использует ссылки A1 на ячейку или диапазон, а ActiveAreaIndex — это индекс с нуля в возвращаемой или переданной последовательности областей

Последовательность областей сохраняет исходный порядок и может содержать перекрывающиеся диапазоны, поскольку порядок выделения и перекрытие являются частью состояния представления листа

Владение снимком

GetSelectedAreas возвращает новый динамический массив, строки и длина которого принадлежат вызывающей стороне, поэтому изменение или освобождение результата не может повлиять на лист

Если у запрошенной области окна нет представленной группы выделения, результат пуст, а ActiveAreaIndex равен -1

Чтение отсутствующей области окна никогда не создает в книге область окна, объект выделения, ячейку или диапазон

Агрегация записей классического XLS

Классический XLS хранит независимую логическую группу выделения для каждой области окна и агрегирует последовательные записи BIFF Selection с одинаковым кодом области окна в исходном порядке

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

При сохранении нетронутой группы сохраняются исходные тела записей, тогда как измененная группа записывается последовательными блоками не более чем по 1369 областей с одинаковым агрегированным активным индексом в каждом блоке

Редактирование одной области окна оставляет группы других областей окна неизменными, а копии книги сохраняют полное состояние выделения по областям окна

Структурные изменения

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

Выжившие области сохраняют свой порядок и идентичность активной области; если активная область удалена, выбирается первый выживший преемник, а если преемников не осталось — последний выживший предшественник

Если удалены все области, группа становится одной ячейкой на границе удаления, а активная ячейка вне выбранной выжившей области откатывается к верхней левой ячейке этой области

Недопустимые классические записи

Некорректные, несмежные или противоречивые классические записи Selection остаются непрозрачными и не раскрываются через типизированный запрос областей

Физическая запись, отклоненная при проверке записей, сообщает xlsDiagnosticSelectionRecordInvalid с диагностическим кодом 1304, тогда как противоречие только на уровне агрегации сообщает одну диагностику группы в конце файла листа (EOF); при сохранении каждое исходное тело записи воспроизводится побайтово

Большие выделения

Разбор областей, нормализация, структурное переназначение и построение снимка используют однопроходные конструкторы или геометрический рост емкости, поэтому большие группы выделения остаются линейными с амортизацией

Координаты прокрутки области окна

TryGetWindowScroll возвращает первую видимую ячейку для одной логической области окна, а ScrollWindow изменяет ее; в обеих подсистемах используются координаты строк и столбцов листа, начиная с единицы

Верхние области окна используют общую строку всего окна, нижние — строку нижней области, левые — общий столбец всего окна, а правые — столбец правой области

Отсутствующая область окна возвращает False, не создавая состояние представления, а выходные данные запроса устанавливаются в нуль; недопустимые координаты также возвращают False до изменения любой оси

Классический XLS сохраняет верхнюю и левую оси в Window2, а нижнюю и правую — в Pane, тогда как XLSX независимо хранит соответствующие значения topLeftCell в sheetView и pane

Атомарные обновления

SelectAreas проверяет каждую ссылку A1 и активный индекс до получения транзакции записи листа

Метод возвращает False для некорректного или пустого ввода, недопустимого активного индекса или области окна, отсутствующей в текущей геометрии разделения или закрепления, при этом прежнее выделение остается неизменным

Успешный вызов возвращает True и сохраняет существующие зависящие от подсистемы объекты выделения и устаревшие API

Пример для Delphi

if Sheet.SelectAreas(xlspBottomRight,
  ['C4:E5', 'D5:F6', 'G7'], 1) then
begin
  Areas := Sheet.GetSelectedAreas(xlspBottomRight,
    ActiveAreaIndex);
  UseSelection(Areas, ActiveAreaIndex);
end;

if Sheet.ScrollWindow(xlspBottomRight, 20, 8) and
   Sheet.TryGetWindowScroll(xlspBottomRight, Row, Col) then
  ShowVisibleCell(Row, Col);

Совместимость

Классическая перегрузка SelectAreas(const Areas; ActiveAreaIndex) и перегрузка XLSX SelectAreas(const Areas; ActiveAreaIndex; APane) остаются доступными без изменений

Классические свойства ScrollRow и ScrollColumn, а также использующие нулевую индексацию члены XLSX SetPaneScroll, GetPaneScroll, ScrollRow и ScrollCol также остаются доступными без изменений

Общий фасад явно преобразует логические имена областей окна, поэтому вызывающие стороны не зависят от числовых кодов областей окна, используемых любым из форматов файлов