API de seleção em painéis de planilha

TXLSWorksheet e TXLSXWorksheet expõem os mesmos métodos conscientes de painéis para ler ou substituir as áreas selecionadas de células e intervalos

Tipos e métodos compartilhados

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;

O texto das áreas usa referências A1 de célula ou intervalo, e ActiveAreaIndex é um índice de base zero na sequência de áreas retornada ou fornecida

A sequência de áreas mantém a ordem de origem e pode conter intervalos sobrepostos, porque a ordem de seleção e a sobreposição fazem parte do estado de exibição da planilha

Propriedade do instantâneo

GetSelectedAreas retorna uma nova matriz dinâmica cujas cadeias de caracteres e cujo comprimento pertencem ao chamador, de modo que alterar ou liberar o resultado não pode modificar a planilha

Quando o painel solicitado não tem nenhum grupo de seleção representado, o resultado é vazio e ActiveAreaIndex é -1

Ler um painel inexistente nunca cria um painel, um objeto de seleção, uma célula ou um intervalo na pasta de trabalho

Agregação de registros do XLS clássico

O XLS clássico mantém um grupo de seleção lógico independente para cada painel e agrega registros BIFF Selection consecutivos com o mesmo código de painel na ordem de origem

A linha ativa, a coluna ativa e o ActiveAreaIndex são compartilhados por todos os registros de um grupo, e o índice endereça a sequência completa de áreas agregadas em vez de um único registro físico

Salvar um grupo intocado preserva os corpos originais de seus registros, enquanto um grupo editado é gravado em blocos consecutivos de no máximo 1369 áreas com o mesmo índice ativo agregado em cada bloco

Editar um painel deixa os grupos dos outros painéis inalterados, e as cópias da pasta de trabalho retêm o estado completo de seleção por painel

Edições estruturais

Inserções ou exclusões de linhas ou colunas inteiras remapeiam os grupos de seleção ordenados de cada painel representado em ambos os motores da pasta de trabalho

As áreas que sobrevivem mantêm sua ordem e a identidade da área ativa; se a área ativa é removida, o primeiro sucessor sobrevivente é selecionado, seguido do último predecessor sobrevivente quando nenhum sucessor permanece

Se todas as áreas forem removidas, o grupo se torna uma única célula no limite da exclusão, enquanto uma célula ativa fora da área sobrevivente escolhida retorna à célula superior esquerda dessa área

Registros clássicos inválidos

Registros BIFF Selection clássicos malformados, não contíguos ou contraditórios permanecem opacos e não são expostos por meio da consulta tipada de áreas

Um registro físico rejeitado durante a validação de registros relata xlsDiagnosticSelectionRecordInvalid com o código de diagnóstico 1304, enquanto uma contradição apenas da agregação relata um diagnóstico de grupo no EOF da planilha; ao salvar, todos os corpos de registro originais são reproduzidos byte a byte

Seleções grandes

A análise e a normalização de áreas, o remapeamento estrutural e a construção do instantâneo usam construtores de passagem única ou crescimento geométrico de capacidade, de modo que grupos de seleção grandes permanecem linearmente amortizados

Coordenadas de rolagem por painel

TryGetWindowScroll retorna a primeira célula visível de um painel lógico e ScrollWindow a altera, usando coordenadas de linha e coluna da planilha com base um em ambos os motores

Os painéis superiores compartilham a linha da janela geral, os painéis inferiores compartilham a linha do painel inferior, os painéis esquerdos compartilham a coluna da janela geral e os painéis direitos compartilham a coluna do painel direito

Um painel inexistente retorna False sem criar estado de exibição, com as saídas da consulta definidas como zero; coordenadas inválidas também retornam False antes que qualquer eixo seja alterado

O XLS clássico persiste os eixos superior e esquerdo em Window2 e os eixos inferior e direito em Pane, enquanto o XLSX retém de forma independente os valores topLeftCell correspondentes de sheetView e pane

Atualizações atômicas

SelectAreas valida cada referência A1 e o índice ativo antes de obter a transação de gravação da planilha

O método retorna False para entrada malformada ou vazia, um índice ativo inválido ou um painel que não existe na geometria atual de divisão ou congelamento, deixando a seleção anterior inalterada

Uma chamada bem-sucedida retorna True e preserva os objetos de seleção existentes específicos do motor e as APIs herdadas

Exemplo em 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);

Compatibilidade

A sobrecarga clássica SelectAreas(const Areas; ActiveAreaIndex) e a sobrecarga XLSX SelectAreas(const Areas; ActiveAreaIndex; APane) permanecem disponíveis sem alterações

As propriedades clássicas ScrollRow e ScrollColumn e os membros XLSX de base zero SetPaneScroll, GetPaneScroll, ScrollRow e ScrollCol também permanecem disponíveis sem alterações

A fachada compartilhada converte explicitamente os nomes lógicos de painéis, de modo que os chamadores não dependem dos códigos numéricos de painel usados por qualquer um dos formatos de arquivo