API GDI+ Flat

  • Artigo

O Windows GDI+ expõe uma API simples composta por cerca de 600 funções, que são implementadas em Gdiplus.dll e declaradas em Gdiplusflat.h. As funções na API simples do GDI+ são encapsuladas por uma coleção de cerca de 40 classes C++. É recomendável que você não chame as funções na API simples diretamente. Sempre que fizer chamadas para o GDI+, chame os métodos e funções fornecidos pelos wrappers C++. Os Serviços de Suporte ao Produto da Microsoft não fornecerão suporte para o código que chamar a API simples diretamente.

Como alternativa aos wrappers C++, o Microsoft .NET Framework fornece um conjunto de classes de wrapper de código gerenciado para o GDI+. Os wrappers de código gerenciado para o GDI+ pertencem aos namespaces a seguir.

Ambos os conjuntos de wrappers (C++ e código gerenciado) usam uma abordagem orientada a objeto, portanto, há algumas diferenças entre a maneira como os parâmetros são passados para os métodos do wrapper e como são passados para funções na API simples. Por exemplo, um dos wrappers C++ é a classe Matrix. Cada objeto Matrix tem um campo, nativeMatrix, que aponta para uma variável interna do tipo GpMatrix. Ao passar parâmetros para um método de um objeto Matrix, esse método passa esses parâmetros (ou um conjunto de parâmetros relacionados) para uma das funções na API simples do GDI+. Mas esse método também passa o campo nativeMatrix (como um parâmetro de entrada) para a função da API simples. O código a seguir mostra como o método Matrix::Shear chama a função GdipShearMatrix(GpMatrix *matrix, REAL shearX, REAL shearY, GpMatrixOrder order).

Status Shear(
      IN REAL shearX, 
      IN REAL shearY,
      IN MatrixOrder order = MatrixOrderPrepend)
{
   ...
   GdipShearMatrix(nativeMatrix, shearX, shearY, order);
   ...
}

Os construtores Matrix passam o endereço de uma variável de ponteiro GpMatrix (como um ponteiro de saída) para a função GdipCreateMatrix(GpMatrix **matrix). A GdipCreateMatrix cria e inicializa uma variável GpMatrix interna e atribui o endereço do GpMatrix à variável de ponteiro. Em seguida, o construtor copia o valor do ponteiro para o campo nativeMatrix.

Matrix()
{
   GpMatrix *matrix = NULL;
   lastResult = DllExports::GdipCreateMatrix(&matrix);
   SetNativeMatrix(matrix);
}

VOID SetNativeMatrix(GpMatrix *nativeMatrix)
{
   this->nativeMatrix = nativeMatrix;
}

Os métodos de clonagem nas classes wrapper não recebem parâmetros, mas, geralmente, passam dois parâmetros para a função subjacente na API simples do GDI+. Por exemplo, o método Matrix::Clone passa nativeMatrix (como um parâmetro de entrada) e o endereço de uma variável de ponteiro GpMatrix (como um parâmetro de saída) para a função GdipCloneMatrix. O código a seguir mostra como o método Matrix::Clone chama a função GdipCloneMatrix(GpMatrix *matrix, GpMatrix **cloneMatrix).

Matrix *Clone() const
{
   GpMatrix *cloneMatrix = NULL;
   ...
   GdipCloneMatrix(nativeMatrix, &cloneMatrix));
   ...
   return new Matrix(cloneMatrix);
 }

As funções na API simples retornam um valor do tipo GpStatus. A enumeração do GpStatus é idêntica à enumeração do Status usada pelos métodos wrapper. Em GdiplusGpStubs.h, o GpStatus é definido da seguinte maneira:

typedef Status GpStatus;

A maioria dos métodos nas classes wrapper retorna um valor de status que indica se o método foi bem-sucedido. No entanto, alguns dos métodos wrapper retornam valores de estado. Ao chamar um método wrapper que retorna um valor de estado, esse método passa os parâmetros apropriados para a função subjacente na API simples do GDI+. Por exemplo, a classe Matrix tem um método Matrix::IsInvertible que passa o campo nativeMatrix e o endereço de uma variável BOOL (como um parâmetro de saída) para a função GdipIsMatrixInvertible. O código a seguir mostra como o método Matrix::IsInvertible chama a função GdipIsMatrixInvertible(GDIPCONST GpMatrix *matrix, BOOL *result).

BOOL IsInvertible() const
{
   BOOL result = FALSE;
   ...
   GdipIsMatrixInvertible(nativeMatrix, &result);
   return result;
}

Outro dos wrappers é a classe Color. Um objeto Color tem um único campo do tipo ARGB, que é definido como um DWORD. Ao passar um objeto Color para um dos métodos wrapper, esse método passará o campo ARGB para a função subjacente na API simples do GDI+. O código a seguir mostra como o método Pen::SetColor chama a função GdipSetPenColor(GpPen *pen, ARGB argb). O método Color::GetValue retorna o valor do campo ARGB.

Status SetColor(IN const Color& color)
{
   ...
   GdipSetPenColor(nativePen, color.GetValue());
}

Os tópicos a seguir mostram a relação entre a API simples do GDI+ e os métodos do wrapper C++.