Gerenciar objetos de caneta de apresentação em PHP

Introdução

O PowerPoint oferece um recurso de caneta que permite desenhar traços livres. A caneta pode ser usada para realçar outros objetos, mostrar conexões e processos, e chamar a atenção para itens específicos em um slide.

Aspose.Slides fornece os tipos necessários para trabalhar com objetos de caneta. Por exemplo, a classe Ink representa um objeto de caneta em um slide.

Diferenças entre Objetos Regulares e Objetos de Caneta

Objetos em um slide do PowerPoint são normalmente representados por objetos Shape. Na sua forma mais simples, um shape é um contêiner que define a área do próprio objeto (sua moldura) juntamente com propriedades como tamanho do contêiner, forma e plano de fundo. Para mais informações, veja Shape Layout Format.

Entretanto, quando o PowerPoint manipula um objeto de caneta, ele ignora todas as propriedades da moldura do objeto (contêiner) exceto seu tamanho. O tamanho da área do contêiner é determinado pelos métodos padrão Shape.getWidth e Shape.getHeight:

ink_powerpoint1

Traços de Caneta

Um traço de caneta é um elemento básico usado para registrar a trajetória de uma caneta enquanto o usuário escreve com caneta digital. Um traço armazena uma sequência de pontos conectados.

A forma mais simples de codificação especifica as coordenadas X e Y de cada ponto de amostra. Quando todos os pontos conectados são renderizados, eles geram uma imagem como esta:

ink_powerpoint2

Propriedades do Pincel para Desenho

Um pincel é usado para desenhar linhas que conectam os pontos de um traço de caneta. O pincel tem sua própria cor e tamanho, representados pelos métodos InkBrush.getColor e InkBrush.getSize.

Definir Cor do Pincel de Caneta

Este código PHP mostra como definir a cor de um pincel de caneta:

$presentation = new Presentation("pres.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $ink = $slide->getShapes()->get_Item(0);
    $brush = $ink->getTraces()[0]->getBrush();
    $brush->setColor(java("java.awt.Color")->RED);
} finally {
    $presentation->dispose();
}

Definir Tamanho do Pincel de Caneta

Este código PHP mostra como definir o tamanho de um pincel de caneta:

$presentation = new Presentation("pres.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $ink = $slide->getShapes()->get_Item(0);
    $brush = $ink->getTraces()[0]->getBrush();
    $brushSize = new Java("java.awt.Dimension", 5, 10);
    $brush->setSize($brushSize);
} finally {
    $presentation->dispose();
}

De modo geral, a largura e a altura de um pincel não coincidem, por isso o PowerPoint não exibe o tamanho do pincel (a seção de dados correspondente está esmaecida). Quando a largura e a altura do pincel coincidem, o PowerPoint exibe seu tamanho assim:

ink_powerpoint3

Para maior clareza, vamos aumentar a altura do objeto de caneta e revisar as dimensões importantes:

ink_powerpoint4

O contêiner (moldura) não leva em conta o tamanho dos pincéis — ele sempre assume que a espessura da linha é zero (veja a imagem anterior).

Portanto, para determinar a área visível de todo o objeto de caneta, o tamanho do pincel de seus traços deve ser considerado. Aqui, o objeto‑alvo (o traço de texto manuscrito) foi dimensionado para o tamanho do contêiner (moldura). Quando o tamanho do contêiner muda, o tamanho do pincel permanece constante, e vice‑versa.

ink_powerpoint5

O PowerPoint usa comportamento semelhante para objetos de texto:

ink_powerpoint6

Controlar Aparência da Caneta Durante Exportação e Renderização

Aspose.Slides fornece a classe InkOptions para controlar como os objetos de caneta aparecem na saída exportada ou renderizada. Você pode usar suas propriedades para ocultar a caneta completamente ou alterar como as operações de máscara do pincel de caneta são interpretadas.

As opções de caneta estão disponíveis nas opções de exportação ou renderização para vários tipos de saída:

Saída Propriedade de opções de caneta
PDF PdfOptions.getInkOptions
HTML HtmlOptions.getInkOptions
SVG SVGOptions.getInkOptions
TIFF TiffOptions.getInkOptions
Slide image RenderingOptions.getInkOptions

Os seguintes métodos da classe InkOptions expõem as mesmas duas configurações:

Ocultar Objetos de Caneta na Saída PDF

Por padrão, os objetos de caneta permanecem visíveis durante a exportação. Para criar uma saída limpa sem anotações manuscritas ou outro conteúdo de caneta, chame InkOptions.setHideInk com true.

O exemplo PHP a seguir exporta uma apresentação para PDF ocultando todos os objetos de caneta:

$presentation = new Presentation("presentation.pptx");
try {
    $pdfOptions = new PdfOptions();
    $pdfOptions->getInkOptions()->setHideInk(true);

    $presentation->save("presentation_without_ink.pdf", SaveFormat::Pdf, $pdfOptions);
} finally {
    $presentation->dispose();
}

Ocultar Objetos de Caneta ao Renderizar um Slide como Imagem

Para ocultar objetos de caneta ao renderizar slides como imagens bitmap, configure RenderingOptions.getInkOptions e passe as opções de renderização para Slide.getImage.

O exemplo PHP a seguir renderiza o primeiro slide como uma imagem PNG sem objetos de caneta:

$presentation = new Presentation("presentation.pptx");
try {
    $renderingOptions = new RenderingOptions();
    $renderingOptions->getInkOptions()->setHideInk(true);

    $slide = $presentation->getSlides()->get_Item(0);
    $image = $slide->getImage($renderingOptions);
    try {
        $image->save("slide_without_ink.png", ImageFormat::Png);
    } finally {
        $image->dispose();
    }
} finally {
    $presentation->dispose();
}

Controlar Renderização de Máscara de Caneta

A configuração InkOptions.getInterpretMaskOpAsOpacity controla como as operações de máscara são interpretadas ao renderizar pincéis de caneta. O valor padrão é true, que usa opacidade. Para usar a operação ROP em vez disso, chame InkOptions.setInterpretMaskOpAsOpacity com false.

O exemplo PHP a seguir exporta um slide para SVG e usa renderização baseada em ROP para operações de máscara de caneta:

$presentation = new Presentation("presentation.pptx");
try {
    $svgOptions = new SVGOptions();
    $svgOptions->getInkOptions()->setInterpretMaskOpAsOpacity(false);

    $outputStream = new Java("java.io.FileOutputStream", "slide.svg");
    try {
        $slide = $presentation->getSlides()->get_Item(0);
        $slide->writeAsSvg($outputStream, $svgOptions);
    } finally {
        $outputStream->close();
    }
} finally {
    $presentation->dispose();
}

A mesma configuração pode ser aplicada através de TiffOptions.getInkOptions ao exportar uma apresentação ou renderizar um slide para TIFF.

Escolher Entre Ocultar ou Preservar a Caneta

Quando você precisar de uma versão limpa de uma apresentação anotada para distribuição sem marcas de revisão, chame InkOptions.setHideInk com true durante a exportação.

Mantenha InkOptions.getHideInk em seu valor padrão false quando as anotações de caneta fizerem parte do conteúdo desejado, como comentários de revisão, notas manuscritas, realces ou desenhos que devem permanecer visíveis no resultado exportado. Isso permite que aplicativos gerem saídas de revisão e finais separadas a partir da mesma apresentação sem modificar os objetos de caneta originais.

Perguntas Frequentes

Posso alterar a cor ou o tamanho de um traço de caneta existente?

Sim. Obtenha o traço via Ink.getTraces, então altere seu InkTrace.getBrush. Chame InkBrush.setColor ou InkBrush.setSize para mudar o pincel.

Ocultar a caneta altera a apresentação original?

Não. Chamar InkOptions.setHideInk afeta apenas o resultado renderizado ou exportado; não remove nem modifica os objetos de caneta na apresentação original.

Quais formatos de exportação suportam opções de caneta?

Você pode configurar opções de caneta para PDF, HTML, SVG, TIFF e imagens bitmap de slides por meio das opções de exportação ou renderização correspondentes mostradas acima.

Leitura adicional

Gerenciar Formas do PowerPoint em PHP Criar e personalizar SmartArt do PowerPoint em PHP