Método ImageAttributes::SetColorKey (gdiplusimageattributes.h)

Artigo
03/05/2025

O método ImageAttributes::SetColorKey define a chave de cor (intervalo de transparência) para uma categoria especificada.

Sintaxe

Status SetColorKey(
  [in, ref]      const Color &   colorLow,
  [in, ref]      const Color &   colorHigh,
  [in, optional] ColorAdjustType type
);

Parâmetros

[in, ref] colorLow

Tipo: const Color

Referência a um objeto Color que especifica o valor baixo da chave de cor.

[in, ref] colorHigh

Tipo: const Color

Referência a um objeto Color que especifica o valor da chave de cor alta.

[in, optional] type

Tipo: ColorAdjustType

Elemento da enumeração ColorAdjustType que especifica a categoria para a qual a chave de cor está definida. O valor padrão é ColorAdjustTypeDefault.

Valor de retorno

Tipo: Status

Se o método for bem-sucedido, ele retornará Ok, que é um elemento da enumeração status de.

Se o método falhar, ele retornará um dos outros elementos da enumeração Status.

Observações

Esse método define os valores de chave de cor alta e baixa para que a disputa de cores possa ser transparente. Qualquer cor que tenha cada um de seus três componentes (vermelho, verde, azul) entre os componentes correspondentes das chaves de cor alta e baixa é transparente.

Um objeto ImageAttributes mantém as configurações de cor e escala de cinza para cinco categorias de ajuste: padrão, bitmap, pincel, caneta e texto. Por exemplo, você pode especificar uma chave de cor para a categoria padrão, uma chave de cor diferente para a categoria bitmap e ainda uma chave de cor diferente para a categoria de caneta.

As configurações de ajuste de cor e escala de cinza padrão se aplicam a todas as categorias que não têm configurações de ajuste próprias. Por exemplo, se você nunca especificar nenhuma configuração de ajuste para a categoria de caneta, as configurações padrão se aplicarão à categoria de caneta.

Assim que você especificar uma configuração de ajuste de escala de cor ou de escala de cinza para uma determinada categoria, as configurações de ajuste padrão não se aplicam mais a essa categoria. Por exemplo, suponha que você especifique uma coleção de configurações de ajuste para a categoria padrão. Se você definir a chave de cor para a categoria de caneta passando ColorAdjustTypePen para o método ImageAttributes::SetColorKey, nenhuma das configurações de ajuste padrão será aplicada a canetas.

Exemplos

O exemplo a seguir cria um objeto Image de um arquivo .bmp. O código também cria um objeto ImageAttributes. A chamada para ImageAttributes::SetColorKey define a chave de cor do bitmap do objeto ImageAttributes para que qualquer cor que atenda a todas as três condições a seguir seja transparente:

O componente vermelho está no intervalo de 100 a 250.
O componente verde está no intervalo de 95 a 245.
O componente azul está no intervalo de 30 a 60.


VOID Example_SetColorKey(HDC hdc)
{
   Graphics graphics(hdc);

   // Create an Image object based on a BMP file.
   // The image has three horizontal stripes.
   // The color of the top stripe has RGB components (90, 90, 20).
   // The color of the middle stripe has RGB components (150, 150, 150).
   // The color of the bottom stripe has RGB components (130, 130, 40).
   Image image(L"ColorKeyTest.bmp");

   // Create an ImageAttributes object, and set its color key.
   ImageAttributes imAtt;
   imAtt.SetColorKey(
      Color(100, 95, 30),
      Color(250, 245, 60),
      ColorAdjustTypeBitmap);

   // Draw the image. Apply the color key.
   // The bottom stripe of the image will be transparent because
   // 100 <= 130 <= 250 and
   // 95  <= 130 <= 245 and
   // 30  <= 40  <= 60.
   graphics.DrawImage(
      &image, 
      Rect(20, 20, image.GetWidth(), image.GetHeight()),  // dest rect
      0, 0, image.GetWidth(), image.GetHeight(),          // source rect
      UnitPixel,
      &imAtt);
}

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP, Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	gdiplusimageattributes.h (inclua Gdiplus.h)
biblioteca	Gdiplus.lib
de DLL	Gdiplus.dll