API de seleção em painéis de folha de cálculo

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

Tipos e métodos partilhados

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 utiliza referências A1 a células ou intervalos, e ActiveAreaIndex é um índice de base zero na sequência de áreas devolvida 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 vista da folha de cálculo

Propriedade do instantâneo

GetSelectedAreas devolve uma nova matriz dinâmica cujas cadeias e cujo comprimento pertencem ao autor da chamada, pelo que alterar ou libertar o resultado não pode modificar a folha de cálculo

Quando o painel pedido 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 no livro de trabalho

Agregação de registos do XLS clássico

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

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

Guardar um grupo intocado preserva os corpos originais dos seus registos, enquanto um grupo editado é escrito 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 do livro de trabalho retêm o estado completo de seleção por painel

Edições estruturais

As inserções ou eliminações de linhas ou colunas inteiras remapeiam os grupos de seleção ordenados de cada painel representado em ambos os motores do livro de trabalho

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

Se todas as áreas forem removidas, o grupo passa a ser uma única célula no limite da eliminação, enquanto uma célula ativa fora da área sobrevivente escolhida recai na célula do canto superior esquerdo dessa área

Registos clássicos inválidos

Os registos Selection clássicos malformados, não contíguos ou contraditórios permanecem opacos e não são expostos através da consulta tipada de áreas

Um registo físico rejeitado durante a validação dos registos comunica xlsDiagnosticSelectionRecordInvalid com o código de diagnóstico 1304, enquanto uma contradição apenas da agregação comunica um diagnóstico de grupo no EOF da folha de cálculo; ao guardar, todos os corpos dos registos originais são reproduzidos byte a byte

Seleções grandes

A análise e a normalização das áreas, o remapeamento estrutural e a construção do instantâneo utilizam construtores de passagem única ou crescimento geométrico da capacidade, pelo que os grupos de seleção grandes se mantêm linearmente amortizados

Coordenadas de deslocamento por painel

TryGetWindowScroll devolve a primeira célula visível de um painel lógico e ScrollWindow altera-a, utilizando coordenadas de linha e coluna da folha de cálculo com base um em ambos os motores

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

Um painel inexistente devolve False sem criar estado de vista, com as saídas da consulta definidas como zero; coordenadas inválidas também devolvem False antes de qualquer eixo ser 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 escrita da folha de cálculo

O método devolve False para uma introdução malformada ou vazia, um índice ativo inválido ou um painel que não existe na geometria atual de divisão ou bloqueio, mantendo a seleção anterior inalterada

Uma chamada bem-sucedida devolve True e preserva os objetos de seleção existentes específicos do motor e as API legadas

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) continuam 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 continuam disponíveis sem alterações

A fachada partilhada converte explicitamente os nomes lógicos dos painéis, pelo que os autores das chamadas não dependem dos códigos numéricos de painel utilizados por qualquer um dos formatos de ficheiro