SetStructElemID

Tagged PDF, Accessibility

Description

Atribui uma string de identidade única ao elemento de estrutura aberto no momento na pilha de tags; o ID é gravado como a entrada /ID no dicionário do elemento de estrutura e é indexado na árvore de nomes /IDTree do documento para que outros elementos possam referenciá-lo (for exemplo, via atributo /Headers de células de tabela); chame isso após BeginTag ou BeginTagEx e antes de EndTag

Syntax

Delphi

Function TPDFlib.SetStructElemID(Const ID: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemID(ID As String) As Long

DLL

int DLSetStructElemID(int InstanceID, const wchar_t * ID);

Parameters

ID	Uma string não vazia que identifica unicamente este elemento de estrutura dentro do documento; escolha um ID que seja significativo e único em todo o documento, como `TH-Col-1`, `TH-Row-2` ou uma string semelhante a um GUID

Return value

Retorna 1 em caso de sucesso; retorna 0 se nenhum documento estiver aberto, nenhuma tag estiver aberta no momento na pilha de tags ou se ID estiver vazio

Remarks

A entrada /ID está definida na ISO 32000-1 §14.7.3.4. Todos os IDs de elementos são coletados em uma árvore de nomes /IDTree plana na raiz da árvore de estrutura quando o documento é salvo; isso permite que ferramentas de acessibilidade e outros elementos procurem elementos por ID. As entradas da /IDTree são classificadas em ordem alfabética pela string do ID

Um caso de uso comum é marcar células de cabeçalho de tabela (TH) com IDs para que as células de dados (TD) possam se associar aos cabeçalhos corretos via SetStructElemHeaders; essa associação é necessária para tabelas complexas sob o PDF/UA-1 (ISO 14289-1 §7.10) e o Critério de Sucesso WCAG 2.x 1.3.1

Se o mesmo ID for atribuído a múltiplos elementos de estrutura, o comportamento será indefinido; apenas um elemento por ID exclusivo deve receber uma determinada string de ID

Example

// Tag a column header cell with an ID for later /Headers reference
PDFlib.BeginTag('TH', 'Product Name', '', '');
PDFlib.SetStructElemID('TH-ProductName');
PDFlib.SetStructElemScope('Column');
PDFlib.DrawText('Product Name', 100, 700);
PDFlib.EndTag;

PDFlib.BeginTag('TH', 'Price', '', '');
PDFlib.SetStructElemID('TH-Price');
PDFlib.SetStructElemScope('Column');
PDFlib.DrawText('Price', 250, 700);
PDFlib.EndTag;

// Tag a data cell referencing both header cells
PDFlib.BeginTag('TD', '', '', '');
PDFlib.SetStructElemHeaders('TH-ProductName,TH-Price');
PDFlib.DrawText('Widget A', 100, 680);
PDFlib.EndTag;