Classe CColorDialog

Permite que você incorpore uma caixa de diálogo de seleção de cores em seu aplicativo.

Sintaxe

class CColorDialog : public CCommonDialog

Membros

Construtores públicos

Nome	Descrição
CColorDialog::CColorDialog	Constrói um objeto CColorDialog.

Métodos públicos

Nome	Descrição
CColorDialog::DoModal	Exibe uma caixa de diálogo de cores e permite que o usuário faça uma seleção.
CColorDialog::GetColor	Retorna uma estrutura COLORREF que contém os valores da cor selecionada.
CColorDialog::GetSavedCustomColors	Recupera cores personalizadas criadas pelo usuário.
CColorDialog::SetCurrentColor	Força a seleção de cores atual para a cor especificada.

Métodos protegidos

Nome	Descrição
CColorDialog::OnColorOK	Substitua para validar a cor inserida na caixa de diálogo.

Membros de Dados Públicos

Nome	Descrição
CColorDialog::m_cc	Uma estrutura usada para personalizar as configurações da caixa de diálogo.

Comentários

Um objeto CColorDialog é uma caixa de diálogo com uma lista de cores definidas para o sistema de exibição. O usuário pode selecionar ou criar uma cor específica da lista, que é relatada de volta ao aplicativo quando a caixa de diálogo é encerrada.

Para construir um objeto CColorDialog, use o construtor fornecido ou derive uma nova classe e use seu próprio construtor personalizado.

Depois que a caixa de diálogo for construída, você poderá definir ou modificar valores na estrutura m_cc para inicializar os valores dos controles da caixa de diálogo. A estrutura m_cc é do tipo CHOOSECOLOR.

Depois de inicializar os controles da caixa de diálogo, chame a função de membro DoModal para exibir a caixa de diálogo e permitir que o usuário selecione uma cor. DoModal retorna a seleção do usuário do botão OK (IDOK) ou Cancelar (IDCANCEL) da caixa de diálogo.

Se DoModal retornar IDOK, você poderá usar uma das funções membro de CColorDialog para recuperar as informações fornecidas pelo usuário.

É possível usar a função CommDlgExtendedError do Windows para determinar se ocorreu um erro durante a inicialização da caixa de diálogo e para saber mais sobre o erro.

CColorDialog depende do arquivo COMMDLG.DLL que é fornecido com as versões 3.1 e posteriores do Windows.

Para personalizar a caixa de diálogo, derive uma classe de CColorDialog, forneça um modelo de caixa de diálogo personalizado e adicione um mapa de mensagem para processar as mensagens de notificação dos controles estendidos. Todas as mensagens não processadas devem ser passadas para a classe base.

A personalização da função de gancho não é necessária.

Observação

Em algumas instalações, o objeto CColorDialog não será exibido com uma tela de fundo cinza se você tiver usado a estrutura para tornar outros objetos CDialog cinza.

Para obter mais informações sobre como usar CColorDialog, confira Classes de diálogo comuns

Hierarquia de herança

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CColorDialog

Requisitos

Cabeçalho: afxdlgs.h

CColorDialog::CColorDialog

Constrói um objeto CColorDialog.

CColorDialog(
    COLORREF clrInit = 0,
    DWORD dwFlags = 0,
    CWnd* pParentWnd = NULL);

Parâmetros

clrInit
A seleção de cores padrão. Se nenhum valor for especificado, o padrão será RGB(0,0,0) (preto).

dwFlags
Um conjunto de sinalizadores que personalizam a função e a aparência da caixa de diálogo. Para obter mais informações, confira a estrutura CHOOSECOLOR no SDK do Windows.

pParentWnd
Um ponteiro para a janela pai ou proprietária da caixa de diálogo.

Exemplo

// Show the Color dialog with all the default settings.
CColorDialog dlg1;
dlg1.DoModal();

// Show the fully opened Color dialog with red as the selected color.
CColorDialog dlg2(RGB(255, 0, 0), CC_FULLOPEN);
dlg2.DoModal();

CColorDialog::DoModal

Chame essa função para exibir a caixa de diálogo de cores comum do Windows e permitir que o usuário selecione uma cor.

virtual INT_PTR DoModal();

Valor de retorno

IDOK ou IDCANCEL. Se IDCANCEL for retornado, chame a função CommDlgExtendedError do Windows para determinar se ocorreu um erro.

IDOK e IDCANCEL são constantes que indicam se o usuário selecionou o botão OK ou Cancelar.

Comentários

Se você quiser inicializar as várias opções de caixa de diálogo de cores definindo membros da estrutura m_cc, faça isso antes de chamar DoModal, mas depois que o objeto da caixa de diálogo for construído.

Depois de chamar DoModal, você poderá chamar outras funções de membro para recuperar as configurações ou a entrada de informações do usuário na caixa de diálogo.

Exemplo

Consulte o exemplo de CColorDialog::CColorDialog.

CColorDialog::GetColor

Chame essa função depois de chamar DoModal para recuperar as informações sobre a cor selecionada pelo usuário.

COLORREF GetColor() const;

Valor de retorno

Um valor COLORREF que contém as informações RGB para a cor selecionada na caixa de diálogo de cores.

Exemplo

// Get the selected color from the CColorDialog.
CColorDialog dlg;
if (dlg.DoModal() == IDOK)
{
   COLORREF color = dlg.GetColor();
   TRACE(_T("RGB value of the selected color - red = %u, ")
         _T("green = %u, blue = %u\n"),
         GetRValue(color), GetGValue(color), GetBValue(color));
}

CColorDialog::GetSavedCustomColors

Os objetos CColorDialog permitem que o usuário, além de escolher cores, defina até 16 cores personalizadas.

static COLORREF* PASCAL GetSavedCustomColors();

Valor de retorno

Um ponteiro para uma matriz de valores de cor de 16 RGB que armazena cores personalizadas criadas pelo usuário.

Comentários

A função de membro GetSavedCustomColors fornece acesso a essas cores. Essas cores poderão ser recuperadas depois que DoModal retornar IDOK.

Cada um dos 16 valores RGB na matriz retornada é inicializado como RGB(255,255,255) (branco). As cores personalizadas escolhidas pelo usuário são salvas somente entre invocações de caixa de diálogo no aplicativo. Se deseja salvar essas cores entre invocações do aplicativo, você deve salvá-las de alguma outra maneira, como em um arquivo de inicialização (.INI).

Exemplo

// Get a pointer to an array of 16 RGB color values that stores
// custom colors created by the user from CColorDialog.
CColorDialog dlg;
if (dlg.DoModal() == IDOK)
{
   COLORREF *ccolor = dlg.GetSavedCustomColors();
   for (int i = 0; i < 16; i++)
   {
      TRACE(_T("RGB value of the selected color - red = %u, ")
            _T("green = %u, blue = %u\n"),
            GetRValue(ccolor[i]),
            GetGValue(ccolor[i]),
            GetBValue(ccolor[i]));
   }
}

CColorDialog::m_cc

Uma estrutura do tipo CHOOSECOLOR, cujos membros armazenam as características e os valores da caixa de diálogo.

CHOOSECOLOR m_cc;

Comentários

Depois de construir um objeto CColorDialog, você poderá usar m_cc para definir vários aspectos da caixa de diálogo antes de chamar a função de membro DoModal.

Exemplo

// The code below uses CColorDialog::m_cc data member to
// customize the settings of CColorDialog. The CColorDialog will
// be shown as full open and with red as the selected color.
CColorDialog dlg;
dlg.m_cc.Flags |= CC_FULLOPEN | CC_RGBINIT;
dlg.m_cc.rgbResult = RGB(255, 0, 0);
dlg.DoModal();

CColorDialog::OnColorOK

Substitua para validar a cor inserida na caixa de diálogo.

virtual BOOL OnColorOK();

Valor de retorno

Diferente de zero se a caixa de diálogo não puder ser ignorada. Caso contrário, 0 para aceitar a cor que foi inserida.

Comentários

Substitua essa função somente se você quiser fornecer validação personalizada da cor selecionada pelo usuário na caixa de diálogo de cores.

O usuário pode selecionar uma cor por um dos dois métodos abaixo:

• Clicando em uma cor na paleta de cores. Os valores RGB da cor selecionada são refletidos nas caixas de edição RGB apropriadas.

• Inserindo valores nas caixas de edição RGB

Substituir OnColorOK permite rejeitar uma cor que o usuário insere em uma caixa de diálogo de cores comum por qualquer motivo específico do aplicativo.

Normalmente, você não precisa usar essa função porque a estrutura fornece validação padrão de cores e exibe uma caixa de mensagem se uma cor inválida é inserida.

Você pode chamar SetCurrentColor de OnColorOK para forçar uma seleção de cores. Depois que OnColorOK for acionado (ou seja, o usuário clica em OK para aceitar a alteração de cor), você poderá chamar GetColor para obter o valor RGB da nova cor.

Exemplo

// Override OnColorOK to validate the color entered to the
// Red, Green, and Blue edit controls. If the color
// is BLACK (i.e. RGB(0, 0,0)), then force the current color
// selection to be the color initially selected when the
// dialog box is created. The color dialog won't close so
// user can enter a new color.
BOOL CMyColorDlg::OnColorOK()
{
   // Value in Red edit control.
   COLORREF clrref = GetColor();
   if (RGB(0, 0, 0) == clrref)
   {
      AfxMessageBox(_T("BLACK is not an acceptable color. ")
                    _T("Please enter a color again"));

      // GetColor() returns initially selected color.
      SetCurrentColor(GetColor());

      // Won't dismiss color dialog.
      return TRUE;
   }

   // OK to dismiss color dialog.
   return FALSE;
}

CColorDialog::SetCurrentColor

Chame essa função depois de chamar DoModal para forçar a seleção de cores atual para o valor de cor especificado no clr.

void SetCurrentColor(COLORREF clr);

Parâmetros

clr
Um valor para a cor RGB.

Comentários

Essa função é chamada de dentro de um manipulador de mensagens ou OnColorOK. A caixa de diálogo atualizará automaticamente a seleção do usuário com base no valor do parâmetro clr.

Exemplo

Consulte o exemplo de CColorDialog::OnColorOK.

Confira também

MDI de exemplo do MFC
DRAWCLI de exemplo do MFC
Classe CCommonDialog
Gráfico da hierarquia