Função SetConsoleCursorPosition

Artigo
12/15/2023

Importante

Este documento descreve a funcionalidade da plataforma do console que não faz mais parte do nosso roteiro de ecossistema. Não recomendamos o uso desse conteúdo em novos produtos, mas continuaremos a oferecer suporte aos usos existentes por tempo indeterminado. Nossa solução moderna preferida se concentra em sequências de terminais virtuais para máxima compatibilidade em cenários de multiplataforma. Você pode encontrar mais informações sobre essa decisão de design em nosso documento Console clássico versus terminal virtual.

Define a posição do cursor no buffer de tela do console especificado.

Sintaxe

BOOL WINAPI SetConsoleCursorPosition(
  _In_ HANDLE hConsoleOutput,
  _In_ COORD  dwCursorPosition
);

Parâmetros

hConsoleOutput [in]
Um identificador do buffer da tela do console. O identificador deve ter o direito de acesso GENERIC_READ. Para saber mais, confira Segurança de buffer e direitos de acesso do console.

dwCursorPosition [entrada]
Uma estrutura COORD que especifica a nova posição do cursor, em caracteres. As coordenadas são a coluna e a linha de uma célula de caractere de buffer de tela. As coordenadas devem estar dentro dos marcos de delimitação do buffer de tela do console.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

A posição do cursor determina onde os caracteres gravados pela função WriteFile ou WriteConsole ou ecoados pela função ReadFile ou ReadConsole são exibidos. Para determinar a posição atual do cursor, use a função GetConsoleScreenBufferInfo.

Se a nova posição do cursor não estiver nos limites da janela do buffer da tela do console, a origem da janela mudará para tornar o cursor visível.

Dica

Essa API tem um terminal virtual equivalente nas seções de posicionamento simples do cursor e posicionamento do cursor. O uso das sequências de controle de nova linha, retorno de carro, backspace e tabulação também pode ajudar no posicionamento do cursor.

Exemplos

Para ver um exemplo, consulte Usar as funções de entrada e saída de alto nível.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ConsoleApi2.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll