Formatação e layout de texto

DirectWrite fornece duas interfaces para formatação de texto: IDWriteTextFormat e IDWriteTextLayout. IDWriteTextFormat descreve apenas o formato do texto e é usado nos casos em que uma cadeia de caracteres inteira deve ter o mesmo tamanho de fonte, estilo, peso e assim por diante. Por outro lado, IDWriteTextLayout encapsula uma cadeia de caracteres de texto e a formatação para intervalos especificados da cadeia de caracteres. Este documento descreve cada interface e seus usos. Para obter mais informações sobre a criação e os métodos dessas interfaces, consulte o IDWriteTextFormat e IDWriteTextLayout páginas de referência.

Este documento contém as seguintes partes:

• IDWriteTextFormat
  • Modificando um IDWriteTextFormat
• IDWriteTextLayout
  • Formatar um intervalo de de texto
  • Opções de renderização

IDWriteTextFormat

Um IDWriteTextFormat objeto é usado para:

• Descreva o formato de uma cadeia de caracteres inteira durante a renderização. Para renderizar uma cadeia de caracteres com vários formatos, use um IDWriteTextLayout objeto.
• Especifique o formato de texto padrão ao criar um IDWriteTextLayout objeto.

Para criar um IDWriteTextFormat objeto, use o IDWriteFactory::CreateTextFormat método e especifique a família de fontes, coleção de fontes, espessura da fonte, tamanho da fonte (em DIPs), nome da localidade.

Modificando um IDWriteTextFormat

Depois que uma interfaceIDWriteTextFormaté criada, alguns valores não podem ser alterados: a família da fonte, coleção, peso e tamanho, bem como o nome da localidade. Para alterar esses valores, um novo objeto IDWriteTextFormat deve ser criado.

IDWriteTextLayout permite alterar as propriedades acima sem recriar nada. IDWriteTextFormat permite fazer alterações de formato que se aplicam a todo o texto, como alinhamento de texto. Se quiser aplicar formatação a intervalos de caracteres específicos, você deve fazê-lo usando um IDWriteTextLayout.

IDWriteTextFormat fornece métodos para definir o alinhamento do texto, a direção do fluxo, a parada de tabulação incremental, o espaçamento entre linhas, o alinhamento de parágrafos, o corte e a quebra automática de texto. Essas propriedades podem ser alteradas a qualquer momento após a criação do IDWriteTextFormat objeto.

IDWriteTextLayout

A interfaceIDWriteTextLayout, ao contrário IDWriteTextFormat, representa um bloco de texto e a formatação associada. IDWriteTextFormat representa informações de formatação inicial. O exemplo a seguir mostra como criar um IDWriteTextLayout objeto usando IDWriteFactory::CreateTextLayout.

// Create a text layout using the text format.
if (SUCCEEDED(hr))
{
    RECT rect;
    GetClientRect(hwnd_, &rect); 
    float width  = rect.right  / dpiScaleX_;
    float height = rect.bottom / dpiScaleY_;

    hr = pDWriteFactory_->CreateTextLayout(
        wszText_,      // The string to be laid out and formatted.
        cTextLength_,  // The length of the string.
        pTextFormat_,  // The text format to apply to the string (contains font information, etc).
        width,         // The width of the layout box.
        height,        // The height of the layout box.
        &pTextLayout_  // The IDWriteTextLayout interface pointer.
        );
}

O texto em um IDWriteTextLayout objeto não pode ser alterado depois que o objeto é criado. Para alterar o texto, você deve excluir o objeto existente e criar um novo IDWriteTextLayout objeto.

Você pode usar um IDWriteTextLayout para formatar intervalos especificados de texto. IDWriteTextLayout também fornece métodos para alterar o estilo e o peso da fonte, além de adicionar recursos de fonte OpenType e testes de ocorrência. Para obter mais informações e uma lista completa de métodos, consulte a página de referênciaIDWriteTextLayout.

Formatar um intervalo de texto

IDWriteTextLayout fornece vários métodos para formatar intervalos de texto. Cada um desses métodos usa uma estrutura DWRITE_TEXT_RANGE como parâmetro para especificar a posição inicial do texto dentro da cadeia de caracteres e o comprimento do intervalo a ser formatado. O exemplo a seguir mostra como definir a espessura da fonte de um intervalo de texto como negrito.

// Set the font weight to bold for the first 5 letters.
DWRITE_TEXT_RANGE textRange = {0, 5};

if (SUCCEEDED(hr))
{
    hr = pTextLayout_->SetFontWeight(DWRITE_FONT_WEIGHT_BOLD, textRange);
}

Opções de renderização

Texto com formatação descrita por apenas um IDWriteTextFormat objeto pode ser renderizado com Direct2D, no entanto, há mais algumas opções para renderizar um objetoIDWriteTextLayout.

A cadeia de caracteres descrita por um objeto IDWriteTextLayout pode ser renderizada usando os métodos abaixo.

1. Renderizar usando Direct2D.
2. Renderizar usando um renderizador de texto personalizado.
3. Renderizar para uma superfície GDI.