Macro CreateWindowA (winuser.h)

Artigo
07/25/2024

Cria uma janela filho, pop-up ou sobreposta. Ele especifica a classe de janela, o título da janela, o estilo da janela e (opcionalmente) a posição inicial e o tamanho da janela. A função também especifica o pai ou o proprietário da janela, se houver, e o menu da janela.

Para usar estilos de janela estendidos além dos estilos compatíveis com CreateWindow, use a função CreateWindowEx.

Sintaxe

HWND CreateWindowA(
  [in, optional] LPCSTR    lpClassName,
  [in, optional] LPCSTR    lpWindowName,
  [in]           DWORD     dwStyle,
  [in]           int       x,
  [in]           int       y,
  [in]           int       nWidth,
  [in]           int       nHeight,
  [in, optional] HWND      hWndParent,
  [in, optional] HMENU     hMenu,
  [in, optional] HINSTANCE hInstance,
  [in, optional] LPVOID    lpParam
);

Parâmetros

[in, optional] lpClassName

Tipo: LPCSTR

Um cadeia de caracteres terminada pornulo ou um atom de classe criado por uma chamada anterior para a função RegisterClass ou RegisterClassEx. O átomo deve estar na palavra de baixa ordem de lpClassName; a palavra de alta ordem deve ser zero. Se lpClassName for uma cadeia de caracteres, ele especifica o nome da classe de janela. O nome da classe pode ser qualquer nome registrado com RegisterClass ou RegisterClassEx, desde que o módulo que registra a classe também seja o módulo que cria a janela. O nome da classe também pode ser qualquer um dos nomes de classe predefinidos do sistema. Para obter uma lista de nomes de classe do sistema, consulte a seção Comentários.

[in, optional] lpWindowName

Tipo: LPCSTR

O nome da janela. Se o estilo da janela especificar uma barra de título, o título da janela apontado por lpWindowName será exibido na barra de título. Ao usar CreateWindow para criar controles, como botões, caixas de seleção e controles estáticos, use lpWindowName para especificar o texto do controle. Ao criar um controle estático com o estilo SS_ICON, use lpWindowName para especificar o nome ou o identificador do ícone. Para especificar um identificador, use a sintaxe "#num".

[in] dwStyle

Tipo: DWORD

O estilo da janela que está sendo criada. Esse parâmetro pode ser uma combinação dos valores de estilo da janela , além dos estilos de controle indicados na seção Comentários.

[in] x

Tipo: int

A posição horizontal inicial da janela. Para uma janela pop-up ou sobreposta, o parâmetro x é a coordenada x inicial do canto superior esquerdo da janela, em coordenadas de tela. Para uma janela filho, x é a coordenada x do canto superior esquerdo da janela em relação ao canto superior esquerdo da área do cliente da janela pai. Se esse parâmetro for definido como CW_USEDEFAULT, o sistema selecionará a posição padrão para o canto superior esquerdo da janela e ignorará o parâmetro y. CW_USEDEFAULT é válido apenas para janelas sobrepostas; se for especificado para uma janela pop-up ou filho, os parâmetros x e y serão definidos como zero.

[in] y

Tipo: int

A posição vertical inicial da janela. Para uma janela sobreposta ou pop-up, o parâmetro y é a coordenada y inicial do canto superior esquerdo da janela, nas coordenadas da tela. Para uma janela filho, y é a coordenada y inicial do canto superior esquerdo da janela filho em relação ao canto superior esquerdo da área do cliente da janela pai. Para uma caixa de listagem, y é a coordenada y inicial do canto superior esquerdo da área do cliente da caixa de listagem em relação ao canto superior esquerdo da área do cliente da janela pai.

Se uma janela sobreposta for criada com o conjunto de bits de estilo WS_VISIBLE e o parâmetro x for definido como CW_USEDEFAULT, o parâmetro y determinará como a janela é mostrada. Se o parâmetro y for CW_USEDEFAULT, o gerenciador de janelas chamará ShowWindow com o sinalizador SW_SHOW após a criação da janela. Se o parâmetro y for algum outro valor, o gerenciador de janelas chamará ShowWindow com esse valor como o parâmetro nCmdShow .

[in] nWidth

Tipo: int

A largura, em unidades de dispositivo, da janela. Para janelas sobrepostas, nWidth é a largura da janela, nas coordenadas da tela ou CW_USEDEFAULT. Se nWidth for CW_USEDEFAULT, o sistema selecionará uma largura e altura padrão para a janela; a largura padrão se estende da coordenada x inicial até a borda direita da tela e a altura padrão se estende da coordenada y inicial até a parte superior da área do ícone. CW_USEDEFAULT é válido apenas para janelas sobrepostas; se CW_USEDEFAULT for especificado para uma janela pop-up ou filho, nWidth e nHeight serão definidos como zero.

[in] nHeight

Tipo: int

A altura, em unidades do dispositivo, da janela. Para janelas sobrepostas, nHeight é a altura da janela, nas coordenadas da tela. Se nWidth estiver definido como CW_USEDEFAULT, o sistema ignorará nHeight.

[in, optional] hWndParent

Tipo: HWND

Um identificador para a janela pai ou proprietário da janela que está sendo criada. Para criar uma janela filho ou uma janela de propriedade, forneça um identificador de janela válido. Esse parâmetro é opcional para janelas pop-up.

Para criar uma janela somente de mensagem, forneça HWND_MESSAGE ou um identificador para uma janela somente mensagem existente.

[in, optional] hMenu

Tipo: HMENU

Um identificador para um menu ou especifica um identificador de janela filho, dependendo do estilo da janela. Para uma janela sobreposta ou pop-up, hMenu identifica o menu a ser usado com a janela; ele poderá ser NULL se o menu de classe for usado. Para uma janela filho, hMenu especifica o identificador de janela filho, um valor inteiro usado por um controle de caixa de diálogo para notificar o pai sobre eventos. O aplicativo determina o identificador de janela filho; deve ser exclusivo para todas as janelas filho com a mesma janela pai.

[in, optional] hInstance

Tipo: HINSTANCE

Um identificador para a instância do módulo a ser associado à janela.

[in, optional] lpParam

Tipo: LPVOID

Um ponteiro para um valor a ser passado para a janela por meio da estrutura CREATETRUCT (membrolpCreateParams) apontado pelo lParam param da mensagem WM_CREATE. Essa mensagem é enviada para a janela criada por essa função antes de retornar.

Se um aplicativo chamar CreateWindow para criar uma janela de cliente MDI, lpParam deverá apontar para uma estrutura CLIENTCREATESTRUCT . Se uma janela do cliente MDI chamar CreateWindow para criar uma janela filho do MDI, lpParam deverá apontar para uma estrutura de MDICREATESTRUCT . lpParam poderá ser NULL se nenhum dado adicional for necessário.

Valor de retorno

Tipo: HWND

Se a função for bem-sucedida, o valor retornado será um identificador para a nova janela.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Observações

Antes de retornar, CreateWindow envia uma mensagem de WM_CREATE para o procedimento de janela. Para janelas filho, pop-up e sobrepostas, CreateWindow envia mensagens WM_CREATE, WM_GETMINMAXINFOe WM_NCCREATE para a janela. O parâmetro lParam da mensagem WM_CREATE contém um ponteiro para uma estrutura CREATESTRUCT. Se o estilo WS_VISIBLE for especificado, CreateWindow enviará à janela todas as mensagens necessárias para ativar e mostrar a janela.

Se a janela criada for uma janela filho, sua posição padrão será na parte inferior da ordem Z. Se a janela criada for uma janela de nível superior, sua posição padrão estará na parte superior da ordem Z (mas abaixo de todas as janelas superiores, a menos que a janela criada seja a própria parte superior).

Para obter informações sobre como controlar se a Barra de Tarefas exibe um botão para a janela criada, consulte Gerenciando botões da barra de tarefas.

Para obter informações sobre como remover uma janela, consulte a função DestroyWindow.

As classes de sistema predefinidas a seguir podem ser especificadas no parâmetro lpClassName. Observe os estilos de controle correspondentes que você pode usar no parâmetro dwStyle.

Classe de sistema	Significado
BUTTON	Designa uma pequena janela filho retangular que representa um botão em que o usuário pode clicar para ativá-la ou desativá-la. Os controles de botão podem ser usados sozinhos ou em grupos e podem ser rotulados ou exibidos sem texto. Os controles de botão normalmente alteram a aparência quando o usuário clica neles. Para obter mais informações, consulte botões Para obter uma tabela dos estilos de botão que você pode especificar no parâmetro dwStyle, consulte estilos de botão.
COMBOBOX	Designa um controle que consiste em uma caixa de listagem e um campo de seleção semelhante a um controle de edição. Ao usar esse estilo, um aplicativo deve exibir a caixa de listagem o tempo todo ou habilitar uma caixa de listagem suspensa. Se a caixa de listagem estiver visível, digitar caracteres no campo de seleção realça a primeira entrada de caixa de listagem que corresponde aos caracteres digitado. Por outro lado, selecionar um item na caixa de listagem exibe o texto selecionado no campo de seleção. Para obter mais informações, consulte Caixas de Combinação. Para obter uma tabela dos estilos de caixa de combinação que você pode especificar no parâmetro dwStyle, consulte estilos de caixa de combinação.
EDITar	Designa uma janela filho retangular na qual o usuário pode digitar texto do teclado. O usuário seleciona o controle e fornece o foco do teclado clicando nele ou movendo-o pressionando a tecla TAB. O usuário pode digitar texto quando o controle de edição exibe um cursor piscando; use o mouse para mover o cursor, selecionar caracteres a serem substituídos ou posicionar o cursor para inserir caracteres; ou use a chave BACKSPACE para excluir caracteres. Para obter mais informações, consulte Editar Controles. Para obter uma tabela dos estilos de controle de edição que você pode especificar no parâmetro dwStyle, consulte Editar Estilos de Controle.
LISTBOX	Designa uma lista de cadeias de caracteres. Especifique esse controle sempre que um aplicativo deve apresentar uma lista de nomes, como nomes de arquivo, dos quais o usuário pode escolher. O usuário pode selecionar uma cadeia de caracteres clicando nela. Uma cadeia de caracteres selecionada é realçada e uma mensagem de notificação é passada para a janela pai. Para obter mais informações, consulte List Boxes. Para obter uma tabela dos estilos de caixa de listagem que você pode especificar no parâmetro dwStyle , consulteestilos de caixa de listagem .
MDICLIENT	Designa uma janela do cliente MDI. Essa janela recebe mensagens que controlam as janelas filho do aplicativo MDI. Os bits de estilo recomendados são WS_CLIPCHILDREN e WS_CHILD. Especifique os estilos WS_HSCROLL e WS_VSCROLL para criar uma janela de cliente MDI que permite ao usuário rolar janelas filho MDI para exibição. Para obter mais informações, consulte interface de vários documentos.
RichEdit	Designa um controle Microsoft Rich Edit 1.0. Essa janela permite que o usuário exiba e edite texto com formatação de caractere e parágrafo e pode incluir objetos COM (Component Object Model) inseridos. Para obter mais informações, consulte rich edit controls. Para obter uma tabela dos estilos de controle de edição avançada que você pode especificar no parâmetro dwStyle, consulte Rich Edit Control Styles.
RICHEDIT_CLASS	Designa um controle Microsoft Rich Edit 2.0. Esses controles permitem que o usuário exiba e edite texto com formatação de caractere e parágrafo e pode incluir objetos COM inseridos. Para obter mais informações, consulte rich edit controls. Para obter uma tabela dos estilos de controle de edição avançada que você pode especificar no parâmetro dwStyle, consulte Rich Edit Control Styles.
scrollbar	Designa um retângulo que contém uma caixa de rolagem e tem setas de direção em ambas as extremidades. A barra de rolagem envia uma mensagem de notificação para sua janela pai sempre que o usuário clica no controle. A janela pai é responsável por atualizar a posição da caixa de rolagem, se necessário. Para obter mais informações, consulte Barras de Rolagem. Para obter uma tabela dos estilos de controle da barra de rolagem que você pode especificar no parâmetro dwStyle, consulte Estilos de Controle da Barra de Rolagem.
ESTÁTICO	Designa um campo de texto simples, uma caixa ou um retângulo usado para rotular, caixa ou separar outros controles. Os controles estáticos não levam nenhuma entrada e não fornecem saída. Para obter mais informações, consulte controles estáticos. Para obter uma tabela dos estilos de controle estático que você pode especificar no parâmetro dwStyle, consulte estilos de controle estático.

CreateWindow é implementado como uma chamada para a função CreateWindowEx , conforme mostrado abaixo.

#define CreateWindowA(lpClassName, lpWindowName, dwStyle, x, y, nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam)\
CreateWindowExA(0L, lpClassName, lpWindowName, dwStyle, x, y, nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam)

#define CreateWindowW(lpClassName, lpWindowName, dwStyle, x, y, nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam)\
CreateWindowExW(0L, lpClassName, lpWindowName, dwStyle, x, y, nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam)

#ifdef UNICODE
#define CreateWindow  CreateWindowW
#else
#define CreateWindow  CreateWindowA
#endif

Exemplos

Para obter um exemplo, consulte Usando classes de janela.

Nota

O cabeçalho winuser.h define CreateWindow como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	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	winuser.h (inclua Windows.h)