Editar operações de texto de controle

  • Artigo

O sistema processa automaticamente todas as operações de texto iniciadas pelo usuário e notifica o aplicativo quando as operações são concluídas.

Os tópicos a seguir abordam as operações de texto iniciadas pelo usuário e a resposta do aplicativo:

Selecionando um controle de edição

O usuário pode selecionar um controle de edição clicando nele com o mouse ou pressionando a tecla TAB para ir até ele. O método tabbing faz parte de uma interface de teclado predefinida que o sistema fornece. Para obter uma descrição completa dessa interface, consulte Caixas de diálogo. Quando o usuário seleciona um controle de edição, o sistema dá ao controle o foco do teclado (consulte "Foco e ativação do teclado" em Sobre a entrada do teclado) e realça seu texto usando vídeo reverso.

Configurando e recuperando texto

Um aplicativo pode definir o texto de um controle de edição usando a função SetWindowText, a função SetDlgItemText ou enviando ao controle uma mensagem WM_SETTEXT.

Para recuperar todo o texto de um controle de edição, primeiro use a função GetWindowTextLength ou a mensagem WM_GETTEXTLENGTH para determinar o tamanho do buffer necessário para conter o texto. Em seguida, recupere o texto usando a função GetWindowText, a função GetDlgItemText ou a mensagem WM_GETTEXT.

Selecionando texto

Depois de selecionar um controle de edição, o usuário pode selecionar texto no controle usando o mouse ou o teclado. Um aplicativo pode recuperar as posições de caracteres inicial e final da seleção atual em um controle de edição enviando ao controle uma mensagem EM_GETSEL. O valor de retorno para a posição final é um maior que o último caractere na seleção (ou seja, a posição do primeiro caractere após o último caractere selecionado).

Um aplicativo também pode selecionar texto em um controle de edição enviando ao controle uma mensagem EM_SETSEL com os índices de caracteres inicial e final para a seleção. Por exemplo, o aplicativo pode usar EM_SETSEL com EM_REPLACESEL para excluir texto de um controle de edição.

Essas três mensagens se aplicam a controles de edição de linha única e multilinha.

Substituindo texto

Um aplicativo pode substituir o texto selecionado em um controle de edição enviando ao controle uma mensagem de EM_REPLACESEL com um ponteiro para o texto de substituição. Se não houver seleção atual, EM_REPLACESEL insere o texto de substituição no ponto de inserção. O aplicativo pode receber um código de notificação EN_ERRSPACE se o texto de substituição exceder a memória disponível. Essa mensagem se aplica aos controles de edição de linha única e multilinha.

Um aplicativo pode usar EM_REPLACESEL para substituir parte do texto de um controle de edição ou a função SetDlgItemText para substituir todo ele.

Alterando a fonte usada por um controle de edição

Um aplicativo pode alterar a fonte que um controle de edição usa enviando a mensagem WM_SETFONT. A maioria dos aplicativos faz isso ao processar a mensagem WM_INITDIALOG. Alterar a fonte não altera o tamanho do controle de edição; Os aplicativos que enviam a mensagem WM_SETFONT talvez precisem recuperar as métricas de fonte para o texto e recalcular o tamanho do controle de edição. Para obter mais informações sobre fontes e métricas de fontes, consulte Fontes e texto.

Recortar, copiar, colar e limpar operações

Há quatro mensagens para mover texto entre um controle de edição e a área de transferência. A mensagem WM_COPY copia a seleção atual (se houver) de um controle de edição para a área de transferência sem excluí-la do controle de edição. A mensagem WM_CUT exclui a seleção atual (se houver) no controle de edição e copia o texto excluído para a área de transferência. A mensagem WM_CLEAR exclui a seleção atual (se houver) de um controle de edição, mas não a copia para a área de transferência (a menos que o usuário pressione a tecla SHIFT). A mensagem WM_PASTE copia o texto da área de transferência para um controle de edição no ponto de inserção. Essas quatro mensagens se aplicam a controles de edição de linha única e multilinha.

Microsoft Windows NT 4.0 e posterior: Um controle de edição inclui um menu de contexto interno que facilita para o usuário mover texto entre o controle de edição e a área de transferência. O menu de contexto aparece quando o usuário clica com o botão direito do mouse no controle. Os comandos no menu de contexto incluem Desfazer, Recortar, Copiar, Colar, Excluir e Selecionar Tudo.

Modificando texto

O usuário pode selecionar, excluir ou mover texto em um controle de edição. O sistema mantém um sinalizador interno para cada controle de edição indicando se o conteúdo do controle foi modificado. O sistema limpa esse sinalizador quando cria o controle e define o sinalizador sempre que o texto no controle é modificado. Um aplicativo pode recuperar o sinalizador de modificação enviando ao controle uma mensagem EM_GETMODIFY. O aplicativo pode então definir ou limpar o sinalizador de modificação enviando ao controle uma mensagem EM_SETMODIFY. Essas mensagens se aplicam a controles de edição de linha única e multilinha.

Limitando o texto inserido pelo usuário

O limite padrão para a quantidade de texto que um usuário pode inserir em um controle de edição é de 32 KB. Um aplicativo pode alterar o limite padrão enviando ao controle uma mensagem EM_SETLIMITTEXT. Essa mensagem define um limite rígido para o número de bytes que o usuário pode inserir em um controle de edição, mas não afeta o texto que já está no controle quando a mensagem foi enviada nem o texto copiado para o controle pela função SetDlgItemText ou a mensagem WM_SETTEXT. Por exemplo, suponha que o aplicativo usa a função SetDlgItemText para colocar 500 bytes em um controle de edição e o usuário também insere 500 bytes (total de 1.000 bytes). Se o aplicativo enviar uma mensagem EM_SETLIMITTEXT limitando o texto inserido pelo usuário a 300 bytes, os 1.000 bytes já no controle de edição permanecerão lá e o usuário não poderá adicionar mais texto. Por outro lado, se o aplicativo enviar uma mensagem EM_SETLIMITTEXT limitando o texto inserido pelo usuário a 1.300 bytes, os 1.000 bytes permanecerão, mas o usuário poderá adicionar mais 300 bytes.

Quando o usuário atinge o limite de caracteres de um controle de edição, o sistema envia ao aplicativo uma mensagem de WM_COMMAND contendo um código de notificação EN_MAXTEXT. Esse código de notificação não significa que a memória foi esgotada, mas que o limite para o texto inserido pelo usuário foi atingido; O usuário não pode inserir mais texto. Para alterar esse limite, um aplicativo deve enviar ao controle uma nova mensagem de EM_SETLIMITTEXT com um limite maior.

Como exemplo do uso de EM_SETLIMITTEXT e EN_MAXTEXT, suponha que o aplicativo deve limitar o usuário a no máximo quatro caracteres em um controle de edição. O aplicativo usaria EM_SETLIMITTEXT para especificar um limite de quatro caracteres. Se o usuário tentasse inserir um quinto caractere, o sistema enviaria um código de notificação EN_MAXTEXT para o aplicativo.

Operações de Caractere e Linha

Há várias mensagens que retornam informações sobre os caracteres e linhas em um controle de edição. A maioria das mensagens retorna um índice, geralmente um número baseado em zero, para se referir a um caractere ou linha. Por exemplo, em um controle de edição de linha única que contém n caracteres, o índice de linha é zero e os caracteres são indexados de zero a n-1. Em um controle de edição de várias linhas que contém linhas m e n caracteres, as linhas são indexadas de zero a m-1 e os caracteres são indexados de zero a n-1. Observe que a indexação de caracteres ignora quebras de linha.

Um aplicativo pode determinar o número de caracteres em um controle de edição enviando a mensagem WM_GETTEXTLENGTH para o controle de edição. Essa mensagem retorna o comprimento, em caracteres (não incluindo o caractere nulo de terminação), do texto em um controle de edição de linha única ou multilinha. A mensagem EM_LINELENGTH retorna o comprimento, em caracteres, de uma linha especificada pelo índice de caracteres de um caractere na linha. O comprimento retornado não inclui nenhum caractere selecionado. Um aplicativo pode usar essas mensagens em um controle de edição de linha única ou multilinha.

A mensagem EM_GETFIRSTVISIBLELINE retorna o índice baseado em zero da linha visível superior em um controle de edição de várias linhas ou o índice baseado em zero do primeiro caractere visível em um controle de edição de linha única. Um aplicativo pode copiar uma linha de um controle de edição para um buffer enviando a mensagem EM_GETLINE para o controle de edição. A linha é especificada por seu índice de linha e a primeira palavra do buffer de recebimento contém o número máximo de bytes a serem copiados para o buffer. O valor de retorno é o número de bytes copiados. Essa mensagem também pode ser usada em um controle de edição de linha única ou multilinha.

Há mensagens exclusivas disponíveis para retornar as informações sobre uma linha em um controle de edição de várias linhas. A mensagem EM_GETLINECOUNT retorna o número de linhas em um controle de edição. A mensagem EM_LINEFROMCHAR retorna o índice da linha que contém um índice de caracteres especificado. A mensagem EM_LINEINDEX retorna o índice do primeiro caractere em uma linha especificada.

Rolando texto em um controle de edição

Para implementar a rolagem em um controle de edição, você pode usar os estilos de rolagem automática discutidos em Editar Tipos e Estilos de Controle ou pode adicionar explicitamente barras de rolagem ao controle de edição. Para adicionar uma barra de rolagem horizontal, use o estilo WS_HSCROLL; Para adicionar uma barra de rolagem vertical, use a WS_VSCROLL estilo. Um controle de edição com barras de rolagem processa suas próprias mensagens da barra de rolagem. Para obter informações detalhadas sobre como adicionar barras de rolagem para editar controles, consulte Barras de rolagem.

O sistema fornece três mensagens que um aplicativo pode enviar para um controle de edição com barras de rolagem. A mensagem EM_LINESCROLL pode rolar um controle de edição de várias linhas vertical e horizontalmente. O parâmetro lParam especifica o número de linhas a serem roladas verticalmente a partir da linha atual e o parâmetro wParam especifica o número de caracteres a serem rolados horizontalmente, a partir do caractere atual. O controle de edição não reconhece mensagens de rolagem horizontal se tiver o estilo ES_CENTER ou ES_RIGHT. A mensagem EM_LINESCROLL se aplica somente a controles de edição de várias linhas.

A mensagem EM_SCROLL rola um controle de edição de várias linhas verticalmente. O parâmetro wParam especifica a ação de rolagem. A mensagem EM_SCROLL se aplica somente a controles de edição de várias linhas. EM_SCROLL tem o mesmo efeito que a mensagem WM_VSCROLL.

A mensagem EM_SCROLLCARET rola o cursor para exibição em um controle de edição.

Definindo paradas de tabulação e margens

Um aplicativo pode definir paradas de tabulação em um controle de edição de várias linhas usando a mensagem EM_SETTABSTOPS. (O padrão para uma parada de tabulação é oito caracteres.) Quando um aplicativo adiciona texto ao controle de edição, os caracteres de tabulação no texto geram automaticamente espaço até a próxima parada de tabulação. A mensagem EM_SETTABSTOPS não faz com que o sistema redesenhe automaticamente o texto. Para fazer isso, um aplicativo pode chamar a função InvalidateRect. A mensagem EM_SETTABSTOPS se aplica somente a controles de edição de várias linhas.

Um aplicativo pode definir a largura das margens esquerda e direita para um controle de edição usando a mensagem EM_SETMARGINS. Depois de enviar essa mensagem, o sistema redesenha o controle de edição para refletir as novas configurações de margem. Um aplicativo pode recuperar a largura da margem esquerda ou direita enviando a mensagem EM_GETMARGINS. Por padrão, as margens do controle de edição são definidas apenas largas o suficiente para acomodar a maior saliência horizontal de caracteres (larguras ABC negativas) para a fonte atual que está sendo usada no controle de edição.

Ocultando a entrada do usuário

Um aplicativo pode usar um caractere de senha em um controle de edição para ocultar a entrada do usuário. Quando um caractere de senha é definido, ele é exibido no lugar de cada caractere digitado pelo usuário. Quando um caractere de senha é removido, o controle exibe os caracteres que o usuário digita. Se o aplicativo criar um controle de edição de linha única usando o estilo ES_PASSWORD, o caractere de senha padrão será um asterisco (*). Um aplicativo pode usar a mensagem EM_SETPASSWORDCHAR para remover ou definir um caractere de senha diferente e a mensagem EM_GETPASSWORDCHAR para recuperar o caractere de senha atual. Essas mensagens se aplicam somente a controles de edição de linha única.

Usando números inteiros

Há duas funções de conversão de números inteiros para controles de edição projetados para conter apenas números. A função SetDlgItemInt cria a representação de cadeia de caracteres de um inteiro especificado (assinado ou não assinado) e envia a cadeia de caracteres para um controle de edição. SetDlgItemInt não retorna nenhum valor. A função GetDlgItemInt cria um inteiro (assinado ou não assinado) a partir de sua representação de cadeia de caracteres em um controle de edição. GetDlgItemInt retorna o inteiro (ou um valor de erro).

Desfazendo operações de texto

Cada controle de edição mantém um sinalizador de desfazer que indica se um aplicativo pode reverter ou desfazer a operação mais recente no controle de edição (desfazendo uma exclusão de texto, por exemplo). O controle de edição define o sinalizador de desfazer para indicar que a operação pode ser desfeita e o redefine para indicar que a operação não pode ser desfeita. Um aplicativo pode determinar a configuração do sinalizador de desfazer enviando ao controle uma mensagem EM_CANUNDO.

Um aplicativo pode desfazer a operação mais recente enviando ao controle uma mensagem EM_UNDO. Uma operação pode ser desfeita, desde que nenhuma outra operação de controle de edição ocorra primeiro. Por exemplo, o usuário pode excluir texto, substituir o texto (desfazer a exclusão) e, em seguida, excluir o texto novamente (desfazer a substituição). A mensagem EM_UNDO se aplica a controles de edição de linha única e multilinha e sempre funciona para controles de edição de linha única.

Um aplicativo pode redefinir o sinalizador de desfazer de um controle de edição enviando ao controle uma mensagem EM_EMPTYUNDOBUFFER. O sistema redefine automaticamente o sinalizador de desfazer sempre que um controle de edição recebe uma mensagem EM_SETHANDLE ou WM_SETTEXT. A função SetDlgItemText envia uma mensagem WM_SETTEXT.

Manipulando quebras de linha e quebra de linha

Um aplicativo pode usar funções de quebra automática de texto com controles de edição de várias linhas para localizar a palavra ou fragmento de palavra que deve ser quebrado para a próxima linha. Usando a função padrão Wordwrap fornecida pelo sistema, as linhas sempre terminam nos espaços entre as palavras. Um aplicativo pode especificar sua própria função Wordwrap fornecendo uma função EditWordBreakProc Wordwrap e enviando ao controle de edição uma mensagem EM_SETWORDBREAKPROC. Um aplicativo pode recuperar o endereço da função Wordwrap atual enviando ao controle uma mensagem EM_GETWORDBREAKPROC.

Um aplicativo pode direcionar um controle de edição de várias linhas para adicionar ou remover um caractere de quebra de linha suave (dois retornos de carro e um feed de linha) automaticamente no final das linhas de texto quebrado. Um aplicativo pode ativar ou desativar esse recurso enviando uma mensagem de EM_FMTLINES ao controle de edição. Essa mensagem se aplica somente a controles de edição de várias linhas e não afeta uma linha que termina com uma quebra de linha rígida (um retorno de carro e um feed de linha inserido pelo usuário). Também em controles de edição de várias linhas, um aplicativo pode especificar o estilo ES_WANTRETURN para solicitar que o sistema insira um retorno de carro quando o usuário pressiona a tecla ENTER no controle de edição.

Recuperando pontos e caracteres

Para determinar o caractere mais próximo de um ponto especificado na área do cliente de um controle de edição, envie a mensagem EM_CHARFROMPOS para o controle. A mensagem retorna o índice de caracteres e o índice de linha do caractere mais próximo do ponto. Da mesma forma, você pode recuperar as coordenadas da área do cliente de um caractere especificado enviando a mensagem EM_POSFROMCHAR. A mensagem retorna as coordenadas x e y do canto superior esquerdo do caractere especificado.

Preenchimento automático de cadeias de caracteres

O preenchimento automático expande cadeias de caracteres que foram parcialmente inseridas em um controle de edição em cadeias de caracteres completas. Por exemplo, quando um usuário começa a inserir uma URL no controle de edição de endereço incorporado na barra de ferramentas do Windows Internet Explorer, o preenchimento automático expande a cadeia de caracteres em uma ou mais URLs completas que são consistentes com a cadeia de caracteres parcial existente. Uma cadeia de caracteres de URL parcial, como "mic", pode ser expandida para "https://www.microsoft.com" ou "https://www.microsoft.com/windows". O preenchimento automático é normalmente usado com controles de edição ou com controles que têm um controle de edição incorporado.

Para obter mais informações, consulte a documentação da interface IAutoComplete e IAutoComplete2.

Script complexo em controles de edição

Um script complexo é uma linguagem cuja forma impressa não é disposta de forma simples. Por exemplo, um script complexo pode permitir renderização bidirecional, modelagem contextual de glifos ou combinação de caracteres. Os controles de edição padrão foram estendidos para oferecer suporte a texto multilíngue e scripts complexos. Isso inclui não apenas entrada e exibição, mas também movimento correto do cursor sobre clusters de caracteres (no script tailandês e Devanagari, por exemplo).

Um aplicativo bem escrito recebe esse suporte automaticamente, sem modificação. Novamente, você deve considerar a adição de suporte para ordem de leitura da direita para a esquerda e alinhamento à direita. Nesse caso, alterne os sinalizadores de estilo estendido da janela de controle de edição para controlar esses atributos, conforme mostrado no exemplo a seguir.

// ID_EDITCONTROL is the control ID in the resource file.
HANDLE hWndEdit = GetDlgItem(hDlg, ID_EDITCONTROL);
LONG lAlign = GetWindowLong(hWndEdit, GWL_EXSTYLE) ;

// To toggle alignment
lAlign ^= WS_EX_RIGHT ;

// To toggle reading order
lAlign ^= WS_EX_RTLREADING ;

Depois de definir o valor lAlign , habilite a nova exibição definindo o estilo estendido da janela de controle de edição da seguinte maneira.

// This assumes your edit control is in a dialog box. If not, 
// get the edit control handle from another source.

SetWindowLong(hWndEdit, GWL_EXSTYLE, lAlign);
InvalidateRect(hWndEdit, NULL, FALSE);

Uniscribe é outro conjunto de funções que fornecem controle fino para o processamento de scripts complexos. Para obter mais informações, consulte Uniscribe.